matplotlib.path

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

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

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

classmatplotlib.path.Path(vertices, codes=None, _interpolation_steps=1, closed=False, readonly=False)[источник]

Базовые классы: 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): Вершины пути в виде массива, маскированного массива или последовательности пар. Маскированные значения, если они есть, будут преобразованы в NaN, которые корректно обрабатываются итератором Agg PathIterator и другими потребителями данных пути, например iter_segments().
codesмассивоподобный объект или None, необязательно: Массив целых чисел длиной N, представляющих коды пути. Если значение не None, длина codes должна совпадать с длиной vertices. Если значение None, vertices будут рассматриваться как последовательность отрезков линии.
_interpolation_stepsint, необязательно: Используется как подсказка для некоторых проекций, например полярной, о том, что этот путь следует линейно интерполировать непосредственно перед отрисовкой. Этот атрибут предназначен главным образом для внутренней реализации и не рассчитан на публичное использование.
closedbool, необязательно: Если codes равно None и closed равно True, vertices будут рассматриваться как отрезки линий замкнутого многоугольника. Обратите внимание, что последняя вершина будет проигнорирована (так как соответствующий код будет установлен в CLOSEPOLY).
readonlybool, необязательно: Заставляет путь вести себя как неизменяемый объект и устанавливает для массивов vertices и codes режим «только для чтения».

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}: Словарь, сопоставляющий коды Path с ожидаемым для каждого кода количеством вершин.

STOP=np.uint8(0)

classmethodarc(theta1, theta2, n=None, is_wedge=False)[исходный код]

Вернуть 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)[исходный код]

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

Параметры:

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

Примечания

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

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

cleaned(transform=None, remove_nans=False, clip=None, *, simplify=False, curves=False, stroke_width=1.0, snap=False, sketch=None)[исходный код]

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

См. также

Path.iter_segments: подробное описание аргументов-ключевых слов.

clip_to_bbox(bbox, inside=True)[исходный код]

Обрезать путь по заданной ограничивающей рамке.

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

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

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

propertycodes

Список кодов в Path в виде одномерного массива.

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

contains_path(path, transform=None)[исходный код]

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

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

contains_point(point, transform=None, radius=0.0)[исходный код]

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

Путь всегда считается замкнутым; то есть, если последний код не 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)[исходный код]

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

Параметры:

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

Возвращает:

массив bool длиной N

Примечания

Текущий алгоритм имеет ряд ограничений:

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

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

deepcopy(memo=None)[исходный код]

Вернуть глубокую копию Path. Path не будет доступен только для чтения, даже если исходный Path доступен только для чтения.

Параметры:

memodict, необязательно: Словарь для кэширования, передаваемый в copy.deepcopy.

Возвращает:

Path: Глубокая копия Path, не доступная только для чтения.

get_extents(transform=None, **kwargs)[исходный код]

Получить ограничивающую рамку пути (Bbox).

Параметры:

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

Возвращает:

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

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

interpolated(steps)[исходный код]

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

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

Параметры:

stepsint: Количество сегментов в новом пути для каждого сегмента исходного пути.

Возвращает:

Path: Интерполированный путь.

intersects_bbox(bbox, filled=True)[исходный код]

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

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

Ограничивающая рамка всегда считается заполненной.

intersects_path(other, filled=True)[исходный код]

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

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

iter_bezier(**kwargs)[исходный код]

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

Параметры:

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

Возвращает:

BBezierSegment: Кривые Безье, составляющие текущий путь. Обратите особое внимание: отдельные точки являются кривыми Безье порядка 0, а линии — кривыми Безье порядка 1 (с двумя контрольными точками).
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)[исходный код]

Перебирает все сегменты кривых в пути.

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

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

Параметры:

transformNone или Transform: Если значение не равно None, к пути будет применено указанное аффинное преобразование.
remove_nansbool, необязательный: Нужно ли удалять из пути все значения NaN и пропускать их с помощью команд MOVETO.
clipNone или (float, float, float, float), необязательный: Если значение не равно None, должно быть задано 4-кортежем (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-кортежем вида (scale, length, randomness), представляющим параметры эскиза.

classmethodmake_compound_path(*args)[исходный код]: Объединяет список объектов Path в один объект Path, удаляя все STOP.

classmethodmake_compound_path_from_polys(XY)[исходный код]

Создает составной объект 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)[исходный код]

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

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

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

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

transformed(transform)[исходный код]

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

См. также

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

classmethodunit_circle()[исходный код]

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

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

classmethodunit_circle_righthalf()[исходный код]

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

Описание используемого приближения см. в Path.circle.

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

classmethodunit_regular_asterisk(numVertices)[исходный код]: Возвращает объект Path для единичной правильной звездочки с указанным числом вершин и радиусом 1.0, центрированной в точке (0, 0).

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

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

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

classmethodwedge(theta1, theta2, n=None)[исходный код]

Возвращает объект 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)[исходный код]

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

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

Параметры:

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)