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: массив с плавающей точкой (N, 2) вершин
codes: N-длинный массив numpy.uint8 кодов пути или 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, коды должны иметь такую же длину, как и вершины. Если None, vertices будут обрабатываться как серия отрезков прямой.
_interpolation_stepsint, необязательно: Используется в качестве подсказки для определённых проекций, таких как Polar, что данный путь должен быть линейно интерполирован непосредственно перед отрисовкой. Этот атрибут в первую очередь является деталью реализации и не предназначен для публичного использования.
closedbool, необязательно: Если codes равно None и closed равно True, вершины будут обрабатываться как отрезки прямой замкнутого многоугольника. Обратите внимание, что последняя вершина затем будет проигнорирована (так как соответствующий код будет установлен на CLOSEPOLY).
readonlybool, необязательно: Делает путь неизменяемым и задаёт вершины и коды как массивы только для чтения.

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: Указывает, должен ли созданный путь иметь аргумент "readonly" при создании экземпляра Path.

Примечания

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

Lancaster, Don. Approximating a Circle or an Ellipse Using Four Bezier Cubic Splines.

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 в виде одномерного массива.

Каждый код — это один из 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) для проверки.
transformTransform, необязательно: Если не 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.
transformTransform, необязательно: Если не 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]

Получить Bbox пути.

Параметры:

transformTransform, необязательно: Преобразование, которое нужно применить к пути перед вычислением границ, если нужно.
**kwargs: Передаётся в iter_bezier.

Возвращает:

matplotlib.transforms.Bbox: Границы пути Bbox([[xmin, ymin], [xmax, ymax]])

statichatch(hatchpattern, density=6)[source]: При заданном спецификаторе штриховки, hatchpattern, генерирует объект Path, который можно использовать в повторяющемся шаблоне штриховки. 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]

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

Параметры:

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

Возвращает:

BBezierSegment: Кривые Безье, составляющие текущий путь. Обратите внимание, что свободные точки являются кривыми Безье нулевого порядка, а линии — кривыми Безье первого порядка (с двумя управляющими точками).
codecode_type: Код, описывающий тип возвращаемой кривой. MOVETO, LINETO, CURVE3 и CURVE4 соответствуют кривым Безье с 1, 2, 3 и 4 управляющими точками соответственно. CLOSEPOLY — это 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, 2x.png, 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]

Преобразовать этот путь в список многоугольников или полилиний. Каждый многоугольник/полилиния — это массив вершин (N, 2). Другими словами, у каждого многоугольника нет инструкций 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 для единичного правильного многоугольника с заданным числом вершин, таким образом, что описанная окружность имеет радиус 1.0, центрированная в (0, 0).

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

propertyvertices: Вершины Path в виде массива (N, 2).

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список Affine2DBase: Если не пусто, это переопределяет master_transform.
offsets(N, 2) массив-подобный
offset_transformAffine2DBase: Преобразование, применяемое к смещениям перед смещением пути.

Примечания

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

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