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: массив чисел с плавающей точкой (N, 2) вершин
• codes: массив numpy.uint8 кодов пути длины N или None

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

Типы кодов:

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

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

• MOVETO1 вершина

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

• LINETO1 вершина

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

• CURVE31 контрольная точка, 1 конечная точка

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

• CURVE42 контрольных точки, 1 конечная точка

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

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

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

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

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

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

Примечание

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

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

Параметры:

vertices(N, 2) массив-подобный

Вершины пути в виде массива, маскированного массива или последовательности пар. Маскированные значения, если таковые имеются, будут преобразованы в NaN, которые затем будут обработаны правильно Agg PathIterator и другими потребителями данных пути, такими как iter_segments().

codesмассив-подобный или None, необязательно

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

_interpolation_stepsint, необязательно

Используется как подсказка для определённых проекций, таких как Polar, что этот путь должен быть линейно интерполирован непосредственно перед рисованием. Этот атрибут в основном является деталью реализации и не предназначен для публичного использования.

closedbool, необязательно

Если codes равно None и closed равно True, вершины будут интерпретированы как отрезки прямых замкнутого многоугольника. Обратите внимание, что последняя вершина затем будет проигнорирована (поскольку соответствующий код будет установлен на CLOSEPOLY).

readonlybool, необязательно

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

CLOSEPOLY=np.uint8(79)

CURVE3=np.uint8(3)

CURVE4=np.uint8(4)

LINETO=np.uint8(2)

MOVETO=np.uint8(1)

NUM_VERTICES_FOR_CODE={np.uint8(0): 1, np.uint8(1): 1, np.uint8(2): 1, np.uint8(3): 2, np.uint8(4): 3, np.uint8(79): 1}

Словарь, сопоставляющий коды пути с количеством вершин, ожидаемых для кода.

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

Каждый код является одним из 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]

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

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

Параметры:

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]

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

Параметры:

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, должен быть 3-элементным кортежем вида (масштаб, длина, случайность), представляющим параметры наброска.

classmethodmake_compound_path(*args)[source]

Объединить список Path в единый Path, удаляя все STOP.

classmethodmake_compound_path_from_polys(XY)[source]

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

(Source code, 2x.png, png)

(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) будут обрезаны.

Полученные многоугольники будут упрощены, если атрибут Path.should_simplify пути равен True.

Если 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)