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]

Bases: object

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

Основное хранилище состоит из двух параллельных массивов numpy:

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

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

Типы кодов:

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

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

Поднять перо и переместиться к заданной вершине.
LINETO1 вершина

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

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

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

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

Если codes имеет значение None, это интерпретируется как 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: псевдоним для uint8

propertycodes: Список кодов в Path в виде одномерного массива numpy. Каждый код соответствует одному из STOP, MOVETO, LINETO, CURVE3, CURVE4 или CLOSEPOLY. Для кодов, которые соответствуют более чем одной вершине (CURVE3 и CURVE4), этот код будет повторяться, чтобы длина vertices и 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: Кривые Безье, составляющие текущий путь. Обратите внимание, что свободные точки — это кривые Безье порядка 0, а линии — кривые Безье порядка 1 (с двумя опорными точками).
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, должно быть тройкой вида (scale, length, randomness), представляющей параметры наброска.

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

classmethodmake_compound_path_from_polys(XY)[source]

Создать составной объект Path для отрисовки нескольких многоугольников с одинаковым числом сторон.

(Source code, png)

Параметры:

XY(numpolys, numsides, 2) массив

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

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

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

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

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

Это полезно для отображения в бэкендах, которые не поддерживают составные пути или кривые Безье.

Если 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 для единичного правильного многоугольника с заданным числом вершин таким образом, чтобы описанная окружность имела радиус 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]

Получение области ограничивающей рамки внутренних объектов PathCollection.

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

Parameters:

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

Notes

Способ, которым paths, transforms и offsets комбинируются, соответствует тому же методу, что и для коллекций: каждый итерируется независимо, поэтому, если у вас есть 3 пути (A, B, C), 2 преобразования (α, β) и 1 смещение (O), их комбинации будут:

(A, α, O)
(B, β, O)
(C, α, O)