matplotlib.path

Модуль для работы с полилиниями, используемыми в Matplotlib.

Основной класс для работы с полилиниями в Matplotlib — Path. Практически все векторное рисование использует Path на каком-то этапе процесса отрисовки.

Сам объект Path не может быть нарисован напрямую, но некоторые подклассы Artist, такие как PathPatch и PathCollection, могут использоваться для удобной визуализации Path.

classmatplotlib.path.Path(vertices, codes=None, _interpolation_steps=1, closed=False, readonly=False)[source]

Базы: object

Последовательность, возможно, несвязанных, возможно, замкнутых, линейных и криволинейных сегментов.

В основе хранения лежат две параллельные массива NumPy:

vertices: массив с плавающей точкой Nx2 вершин
codes: массив uint8 длины N кодов пути или None

Эти два массива всегда имеют одинаковую длину в первом измерении. Например, для представления кубической кривой необходимо указать три вершины и три CURVE4 кода.

Типы кодов:

STOP1 вершина (игнорируется)

Маркер конца всего пути (в настоящее время не требуется и игнорируется)
MOVETO1 вершина

Поднять перо и переместить его в заданную вершину.
LINETO1 вершина

Нарисовать линию от текущей позиции до заданной вершины.
CURVE31 контрольная точка, 1 конечная точка

Нарисовать квадратичную кривую Безье от текущей позиции, с заданной контрольной точкой, до заданной конечной точки.
CURVE42 контрольные точки, 1 конечная точка

Нарисовать кубическую кривую Безье от текущей позиции, с заданными контрольными точками, до заданной конечной точки.
CLOSEPOLY1 вершина (игнорируется)

Нарисовать отрезок линии до начальной точки текущей ломаной.

Если codes равно None, то vertices интерпретируется как MOVETO за которым следует ряд LINETO.

Пользователи объектов Path не должны напрямую обращаться к массивам vertices и codes. Вместо этого они должны использовать iter_segments или cleaned, чтобы получить пары вершина/код. Это особенно помогает последовательно обрабатывать случай, когда codes равно None.

Некоторое поведение объектов Path может быть настроено с помощью rcParams. См. rcParams, ключи которых начинаются с 'path.'.

Примечание

Массивы vertices и codes следует рассматривать как неизменяемые — в конструкторе сделано несколько оптимизаций и предположений, которые не будут изменены при изменении данных.

Создайте новый путь с заданными вершинами и кодами.

Параметры

vertices(N, 2) array-like: Вершины пути, как массив, массив с маской или последовательность пар. Маскированные значения, если таковые имеются, будут преобразованы в NaN, которые затем корректно обрабатываются Agg PathIterator и другими потребителями данных пути, такими как iter_segments().
codesarray-like или None, необязательно: Массив целых чисел длины N, представляющий коды пути. Если не None, codes должны иметь такую же длину, как vertices. Если None, vertices будут рассматриваться как последовательность отрезков прямых.
_interpolation_stepsint, необязательно: Используется как подсказка для некоторых проекций, таких как Polar, о том, что этот путь должен быть линейно интерполирован непосредственно перед отрисовкой. Этот атрибут в первую очередь является деталью реализации и не предназначен для использования в общедоступном режиме.
closedbool, необязательно: Если codes равно None, а closed равно True, vertices будут обрабатываться как отрезки прямых замкнутого многоугольника. Обратите внимание, что последняя вершина затем будет пропущена (так как соответствующий код будет установлен в CLOSEPOLY).
readonlybool, необязательно: Делает путь неизменяемым и устанавливает массивы vertices и codes в качестве только для чтения.

CLOSEPOLY=79

CURVE3=3

CURVE4=4

LINETO=2

MOVETO=1

NUM_VERTICES_FOR_CODE={0: 1, 1: 1, 2: 1, 3: 2, 4: 3, 79: 1}: Словарь, сопоставляющий коды Path с количеством вершин, которое ожидает код.

STOP=0

classmethodarc(theta1, theta2, n=None, is_wedge=False)[source]

Возвращает Path для дуги единичной окружности от углов theta1 до theta2 (в градусах).

theta2 разворачивается, чтобы получить кратчайшую дугу в пределах 360 градусов. То есть, если theta2 > theta1 + 360, дуга будет от theta1 до theta2 - 360, а не полная окружность плюс некоторое дополнительное перекрытие.

Если n предоставлен, это число сегментов сплайна. Если n не указан, количество сегментов сплайна определяется на основе разницы между theta1 и theta2.

Masionobe, L. 2003. Рисование эллиптической дуги с помощью ломаных, квадратичных или кубических кривых Безье.

classmethodcircle(center=(0.0, 0.0), radius=1.0, readonly=False)[source]

Возвращает Path, представляющий окружность заданного радиуса и центра.

Параметры

center(float, float), по умолчанию: (0, 0): Центр окружности.
radiusfloat, по умолчанию: 1: Радиус окружности.
readonlybool: Устанавливает ли создаваемый путь аргумент "только для чтения" при создании экземпляра Path.

Примечания

Окружность аппроксимируется с помощью 8 кубических кривых Безье, как описано в

Lancaster, Don. Приближение окружности или эллипса с использованием четырех кубических сплайнов Безье.

cleaned(transform=None, remove_nans=False, clip=None, *, simplify=False, curves=False, stroke_width=1.0, snap=False, sketch=None)[source]

Возвращает новый Path с очищенными вершинами и кодами в соответствии с параметрами.

См. также

Path.iter_segments: для получения подробностей об именованных параметрах.

clip_to_bbox(bbox, inside=True)[source]

Обрезать путь до заданной рамки.

Путь должен состоять из одного или нескольких замкнутых многоугольников. Этот алгоритм не будет корректно работать для незамкнутых путей.

Если inside равно True, то обрезать до внутренней части рамки, в противном случае — до внешней части.

code_type: псевдоним numpy.uint8

propertycodes: Список кодов в Path в виде одномерного массива numpy. Каждый код — это один из STOP, MOVETO, LINETO, CURVE3, CURVE4 или CLOSEPOLY. Для кодов, соответствующих более чем одной вершине (CURVE3 и CURVE4), этот код будет повторяться, чтобы длина self.vertices и self.codes всегда была одинаковой.

contains_path(path, transform=None)[source]

Возвращает, полностью ли данный путь содержится в этом (замкнутом) пути.

Если transform не None, путь будет преобразован перед проверкой на включение.

contains_point(point, transform=None, radius=0.0)[source]

Возвращает, содержит ли область, заключённая внутри пути, данную точку.

Путь всегда рассматривается как замкнутый; т.е. если последний код не CLOSEPOLY, предполагается неявный сегмент, соединяющий последнюю вершину с первой вершиной.

Параметры

point(float, float): Точка (x, y) для проверки.
transformmatplotlib.transforms.Transform, необязательно: Если не None, point будет сравниваться с self , преобразованной с помощью transform; т.е. для правильной проверки transform должен преобразовать путь в систему координат point.
radiusfloat, по умолчанию: 0: Добавить дополнительный отступ к пути в координатах point. Путь расширяется по касательной на radius/2; т.е. если вы нарисуете путь с шириной линии radius, все точки на линии всё ещё будут считаться содержащимися в области. И наоборот, отрицательные значения сужают область: Точки на воображаемой линии будут считаться за пределами области.

Возвращает

bool

Примечания

У текущего алгоритма есть некоторые ограничения:

Результат неопределён для точек точно на границе (т.е. на пути, смещённом на radius/2).
Результат неопределён, если нет заключённой области, т.е. все вершины лежат на прямой.
Если ограничивающие линии пересекаются друг с другом из-за смещения radius, результат не гарантируется.

contains_points(points, transform=None, radius=0.0)[source]

Возвращает, содержит ли область, заключённая внутри пути, заданные точки.

Параметры

points(N, 2) массив: Точки для проверки. Столбцы содержат значения x и y.
transformmatplotlib.transforms.Transform, необязательно: Если не None, points будут сравниваться с self , преобразованной с помощью transform; т.е. для правильной проверки transform должен преобразовать путь в систему координат points.
radiusfloat, по умолчанию: 0: Добавить дополнительный отступ к пути в координатах points. Путь расширяется по касательной на radius/2; т.е. если вы нарисуете путь с шириной линии radius, все точки на линии всё ещё будут считаться содержащимися в области. И наоборот, отрицательные значения сужают область: Точки на воображаемой линии будут считаться за пределами области.

Возвращает

массив bool длины N

Примечания

У текущего алгоритма есть некоторые ограничения:

Результат неопределён для точек точно на границе (т.е. на пути, смещённом на radius/2).
Результат неопределён, если нет заключённой области, т.е. все вершины лежат на прямой.
Если ограничивающие линии пересекаются друг с другом из-за смещения radius, результат не гарантируется.

copy()[source]: Возвращает поверхностную копию Path, которая будет совместно использовать вершины и коды с исходным Path.

deepcopy(memo=None)[source]: Возвращает глубокую копию Path. Path не будет только для чтения, даже если исходный Path является таковым.

get_extents(transform=None, **kwargs)[source]

Получить прямоугольник области определения пути.

Параметры

transformmatplotlib.transforms.Transform, необязательно: Преобразование, применяемое к пути перед вычислением области определения, если таковое имеется.
**kwargs: Передаются в iter_bezier.

Возвращает

matplotlib.transforms.Bbox: Область определения пути Bbox([[xmin, ymin], [xmax, ymax]])

statichatch(hatchpattern, density=6)[source]: На основе спецификатора штриховки, hatchpattern, генерирует путь, который может быть использован в повторяющейся штриховке. density — количество линий на квадратный единицу.

interpolated(steps)[source]

Возвращает новый путь, пересэмплированный до длины N x steps.

Коды, отличные от LINETO, не обрабатываются корректно.

intersects_bbox(bbox, filled=True)[source]

Возвращает, пересекает ли этот путь заданный Bbox.

Если filled равно True, то это также возвращает True, если путь полностью охватывает Bbox (т.е., путь рассматривается как заполненный).

Прямоугольник области определения всегда считается заполненным.

intersects_path(other, filled=True)[source]

Возвращает, пересекается ли этот путь с другим заданным путем.

Если filled равно True, то это также возвращает True, если один путь полностью охватывает другой (т.е., пути рассматриваются как заполненные).

iter_bezier(**kwargs)[source]

Итерируется по каждой кривой Безье (включая линии) в пути.

Параметры

**kwargs: Передаются в iter_segments.

Возвращает

Bmatplotlib.bezier.BezierSegment: Кривые Безье, составляющие текущий путь. Обратите внимание, что отдельные точки — это кривые Безье нулевого порядка, а линии — кривые Безье первого порядка (с двумя опорными точками).
codePath.code_type: Код, описывающий тип возвращаемой кривой. Path.MOVETO, Path.LINETO, Path.CURVE3, Path.CURVE4 соответствуют кривым Безье с 1, 2, 3 и 4 опорными точками (соответственно). Path.CLOSEPOLY — это Path.LINETO с опорными точками, правильно выбранными на основе начальных/конечных точек текущей линии.

iter_segments(transform=None, remove_nans=True, clip=None, snap=False, stroke_width=1.0, simplify=None, curves=True, sketch=None)[source]

Итерируется по всем сегментам кривых в пути.

В каждой итерации возвращается пара (vertices, code), где vertices — последовательность из 1–3 пар координат, а code — код Path.

Кроме того, этот метод может предоставить ряд стандартных очисток и преобразований пути.

Параметры

transformNone или Transform: Если не None, заданное аффинное преобразование будет применено к пути.
remove_nansbool, необязательно: Удалять ли все значения NaN из пути и пропускать их с помощью команд MOVETO.
clipNone или (float, float, float, float), необязательно: Если не None, должно быть четвёркой (x1, y1, x2, y2), определяющей прямоугольник, в котором нужно обрезать путь.
snapNone или bool, необязательно: Если True, все узлы будут привязаны к пикселям; если False, не привязываться. Если None, привязываться, если путь содержит только сегменты, параллельные осям x или y, и не более 1024 из них.
stroke_widthfloat, необязательно: Ширина линии, рисуемой по пути (используется для привязки пути).
simplifyNone или bool, необязательно: Упрощать ли путь, удаляя вершины, не влияющие на его вид. Если None, используйте атрибут should_simplify. См. также rcParams["path.simplify"] (по умолчанию: True) и rcParams["path.simplify_threshold"] (по умолчанию: 0.111111111111).
curvesbool, необязательно: Если True, сегменты кривых будут возвращены как сегменты кривых. Если False, все кривые будут преобразованы в сегменты прямых.
sketchNone или последовательность, необязательно: Если не None, должно быть тройкой вида (масштаб, длина, случайность), представляющей параметры зарисовки.

classmethodmake_compound_path(*args)[source]: Создаёт составной путь из списка объектов Path. Слепо удаляет все контрольные точки Path.STOP.

classmethodmake_compound_path_from_polys(XY)[source]

Создать объект составного пути для отрисовки нескольких многоугольников с равным числом сторон. XY — это массив NumPy размером (numpolys x numsides x 2) вершин. Возвращаемый объект является Path.

(Исходный код, png, pdf)

propertyreadonly: True, если Path является только для чтения.

propertyshould_simplify: True, если массив вершин должен быть упрощен.

propertysimplify_threshold: Доля пиксельного различия, ниже которой вершины будут упрощены.

to_polygons(transform=None, width=0, height=0, closed_only=True)[source]

Преобразовать этот путь в список многоугольников или ломаных линий. Каждый многоугольник/ломаная линия — это массив Nx2 вершин. Другими словами, каждый многоугольник не содержит инструкций MOVETO или кривых. Это полезно для отображения в бэкэндах, которые не поддерживают составные пути или кривые Безье.

Если width и height оба отличны от нуля, линии будут упрощены, так что вершины за пределами (0, 0), (width, height) будут обрезаны.

Если closed_only равен True (по умолчанию), будут возвращены только замкнутые многоугольники, у которых последняя точка совпадает с первой. Любые незамкнутые ломаные линии в пути будут явно замкнуты. Если closed_only равен False, любые незамкнутые многоугольники в пути будут возвращены как незамкнутые многоугольники, а замкнутые многоугольники будут возвращены явно замкнутыми, установив последнюю точку такой же, как и первую.

transformed(transform)[source]

Возвращает преобразованную копию пути.

См. также

matplotlib.transforms.TransformedPath: Специализированный класс пути, который кэширует преобразованный результат и автоматически обновляется при изменении преобразования.

classmethodunit_circle()[source]

Возвращает только для чтения Path единичной окружности.

В большинстве случаев Path.circle() будет тем, что вам нужно.

classmethodunit_circle_righthalf()[source]

Возвращает Path правой половины единичной окружности.

См. Path.circle для справки по используемому приближению.

classmethodunit_rectangle()[source]: Возвращает Path экземпляр единичного прямоугольника от (0, 0) до (1, 1).

classmethodunit_regular_asterisk(numVertices)[source]: Возвращает Path для единичной регулярной звездочки с заданным числом вершин и радиусом 1,0, центрированной в (0, 0).

classmethodunit_regular_polygon(numVertices)[source]: Возвращает Path экземпляр для единичного регулярного многоугольника с заданным numVertices, таким что описанная окружность имеет радиус 1.0, центрированную в (0, 0).

classmethodunit_regular_star(numVertices, innerCircle=0.5)[source]: Возвращает Path для единичной регулярной звезды с заданным числом вершин и радиусом 1.0, центрированной в (0, 0).

propertyvertices: Список вершин в Path в виде массива NumPy Nx2.

classmethodwedge(theta1, theta2, n=None)[source]

Возвращает Path для сектора единичной окружности от углов theta1 до theta2 (в градусах).

theta2 разворачивается, чтобы получить самый короткий сектор в пределах 360 градусов. То есть, если theta2 > theta1 + 360, сектор будет от theta1 до theta2 - 360, а не полная окружность плюс некоторое дополнительное перекрытие.

Если n предоставлено, это число сегментов сплайнов. Если n не предоставлено, число сегментов сплайнов определяется на основе разницы между theta1 и theta2.

См. Path.arc для справки по используемому приближению.

matplotlib.path.get_path_collection_extents(master_transform, paths, transforms, offsets, offset_transform)[source]

Учитывая последовательность Path, объектов Transform и смещений, как в PathCollection, возвращает рамку, которая охватывает все объекты.

Параметры

master_transformTransform: Глобальное преобразование, применяемое ко всем путям.
pathsсписок Path
transformsсписок Affine2D
offsetsмассив (N, 2)
offset_transformAffine2D: Преобразование, применяемое к смещениям перед смещением пути.

Примечания

Способ объединения paths, transforms и offsets аналогичен методу для наборов: каждый объект перебирается независимо, поэтому если у вас 3 пути, 2 преобразования и 1 смещение, их комбинации выглядят так:

(A, A, A), (B, B, A), (C, A, A)