Cluster · разработчикам

Container

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

Получение объекта

canvas = app.images.canvas(800, 400)

init

Создаёт Container. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

def __init__(layers: list, width: float, height: float) -> None: ...

Аргументы

layers: list, обязательный. Упорядоченные описания дочерних слоёв.
width: float, обязательный. Размер контейнера в пикселях.
height: float, обязательный. Размер контейнера в пикселях.

Результат

None. Создаёт Container. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

Права

Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.

Ошибки

Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.

Пример

# Обычный способ получения объекта:
canvas = app.images.canvas(800, 400)

add

Копирует описание слоя и добавляет в контейнер. Для kind=group возвращает Group. Полная проверка сцены выполняется в Canvas.build().

def add(data: LayerData) -> Layer: ...

Аргументы

data: LayerData, обязательный. Описание слоя: id, kind, x, y, width, height и свойства его вида. Для group также layers; полная форма в IMAGE_GENERATOR.md.

Результат

Layer. Копирует описание слоя и добавляет в контейнер. Для kind=group возвращает Group. Полная проверка сцены выполняется в Canvas.build().

Права

Ошибки

ValueError('A layer with this ID already exists'): условие проверяется до продолжения операции.
KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

layer = canvas.add({"id": "accent", "kind": "rect", "x": 20, "y": 20, "width": 100, "height": 60, "fill": "#a78bfa"})

layer

Добавляет слой заданного вида с геометрией и стилем.

def layer(kind: str, id: str, x: float, y: float, width: float, height: float, **style: JSON) -> Layer: ...

Аргументы

kind: str, обязательный. Вид объекта или операции из допустимого перечня конкретного класса.
id: str, обязательный. Уникальный во всей сцене ID слоя, от 1 до 128 символов.
x: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
y: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
width: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
height: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
style: JSON, произвольные именованные аргументы. Именованные свойства выбранного слоя: допустимые поля и пределы приведены в IMAGE_GENERATOR.md. Свойства другого типа слоя отклоняются при build().

Результат

Layer. Добавляет слой заданного вида с геометрией и стилем.

Права

Ошибки

KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

layer = canvas.layer("rect", "accent", 20, 20, 100, 60, fill="#a78bfa")

rect

Добавляет прямоугольник, при необходимости со скруглением и контуром.

def rect(id: str, x: float, y: float, width: float, height: float, **style: JSON) -> Layer: ...

Аргументы

id: str, обязательный. Уникальный во всей сцене ID слоя, от 1 до 128 символов.
x: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
y: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
width: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
height: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
style: JSON, произвольные именованные аргументы. Именованные свойства выбранного слоя: допустимые поля и пределы приведены в IMAGE_GENERATOR.md. Свойства другого типа слоя отклоняются при build().

Результат

Layer. Добавляет прямоугольник, при необходимости со скруглением и контуром.

Права

Ошибки

KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

result = canvas.rect("background", 20, 20, 400, 400, fill="#a78bfa")

ellipse

Добавляет эллипс в указанных границах.

def ellipse(id: str, x: float, y: float, width: float, height: float, **style: JSON) -> Layer: ...

Аргументы

id: str, обязательный. Уникальный во всей сцене ID слоя, от 1 до 128 символов.
x: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
y: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
width: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
height: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
style: JSON, произвольные именованные аргументы. Именованные свойства выбранного слоя: допустимые поля и пределы приведены в IMAGE_GENERATOR.md. Свойства другого типа слоя отклоняются при build().

Результат

Layer. Добавляет эллипс в указанных границах.

Права

Ошибки

KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

result = canvas.ellipse("background", 20, 20, 400, 400, fill="#a78bfa")

gradient

Добавляет прямоугольник с градиентом start/end.

def gradient(id: str, x: float, y: float, width: float, height: float, start: str, end: str, **style: JSON) -> Layer: ...

Аргументы

id: str, обязательный. Уникальный во всей сцене ID слоя, от 1 до 128 символов.
x: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
y: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
width: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
height: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
start: str, обязательный. Цвет #RRGGBB или #RRGGBBAA; None допускается только для необязательного цвета.
end: str, обязательный. Цвет #RRGGBB или #RRGGBBAA; None допускается только для необязательного цвета.
style: JSON, произвольные именованные аргументы. Именованные свойства выбранного слоя: допустимые поля и пределы приведены в IMAGE_GENERATOR.md. Свойства другого типа слоя отклоняются при build().

Результат

Layer. Добавляет прямоугольник с градиентом start/end.

Права

Ошибки

KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

layer = canvas.gradient("shade", 0, 0, 800, 400, "#18151f", "#34254c")

text

Добавляет текст с переносами и выбранным переполнением в заданных границах.

def text(id: str, text: str, x: float, y: float, width: float, height: float, **style: JSON) -> Layer: ...

Аргументы

id: str, обязательный. Уникальный во всей сцене ID слоя, от 1 до 128 символов.
text: str, обязательный. Текст или собранный Text там, где поддерживается преобразование. В короткие методы клиента передавай str(Text).
x: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
y: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
width: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
height: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
style: JSON, произвольные именованные аргументы. Именованные свойства выбранного слоя: допустимые поля и пределы приведены в IMAGE_GENERATOR.md. Свойства другого типа слоя отклоняются при build().

Результат

Layer. Добавляет текст с переносами и выбранным переполнением в заданных границах.

Права

Ошибки

KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

result = canvas.text("background", "Ready", 20, 20, 400, 400, size=24)

image

Добавляет ранее загруженный ресурс генератора по asset. URL и файлы сервера напрямую не читаются.

def image(id: str, asset: str, x: float, y: float, width: float, height: float, **style: JSON) -> Layer: ...

Аргументы

id: str, обязательный. Уникальный во всей сцене ID слоя, от 1 до 128 символов.
asset: str, обязательный. ID временного ресурса, полученного через Drawing.upload(); не URL и не файловый путь.
x: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
y: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
width: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
height: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
style: JSON, произвольные именованные аргументы. Именованные свойства выбранного слоя: допустимые поля и пределы приведены в IMAGE_GENERATOR.md. Свойства другого типа слоя отклоняются при build().

Результат

Layer. Добавляет ранее загруженный ресурс генератора по asset. URL и файлы сервера напрямую не читаются.

Права

Ошибки

KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

layer = canvas.image("picture", asset.id, 20, 20, 100, 60, radius=8)

group

Добавляет группу с собственными координатами и вложенными слоями.

def group(id: str, x: float, y: float, width: float, height: float, **style: JSON) -> Group: ...

Аргументы

id: str, обязательный. Уникальный во всей сцене ID слоя, от 1 до 128 символов.
x: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
y: float, обязательный. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
width: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
height: float, обязательный. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
style: JSON, произвольные именованные аргументы. Именованные свойства выбранного слоя: допустимые поля и пределы приведены в IMAGE_GENERATOR.md. Свойства другого типа слоя отклоняются при build().

Результат

Group. Добавляет группу с собственными координатами и вложенными слоями.

Права

Ошибки

KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

group = canvas.group("card", 20, 20, 400, 200)

points

Добавляет линию или многоугольник с геометрией, рассчитанной по точкам.

def points(kind: str, id: str, points: list, **style: JSON) -> Layer: ...

Аргументы

kind: str, обязательный. Вид объекта или операции из допустимого перечня конкретного класса.
id: str, обязательный. Уникальный во всей сцене ID слоя, от 1 до 128 символов.
points: list, обязательный. Координаты точек. Для line от 2 до 64, polygon от 3 до 64; значения от -4096 до 4096.
style: JSON, произвольные именованные аргументы. Именованные свойства выбранного слоя: допустимые поля и пределы приведены в IMAGE_GENERATOR.md. Свойства другого типа слоя отклоняются при build().

Результат

Layer. Добавляет линию или многоугольник с геометрией, рассчитанной по точкам.

Права

Ошибки

ValueError('Points are required'): условие проверяется до продолжения операции.
KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

layer = canvas.points("line", "trace", [(0, 0), (100, 50)], stroke="#a78bfa")

line

Добавляет ломаную минимум из двух точек с цветом и шириной контура.

def line(id: str, points: list, color: str, width: int = 1) -> Layer: ...

Аргументы

id: str, обязательный. Уникальный во всей сцене ID слоя, от 1 до 128 символов.
points: list, обязательный. Координаты точек. Для line от 2 до 64, polygon от 3 до 64; значения от -4096 до 4096.
color: str, обязательный. Цвет #RRGGBB или #RRGGBBAA; None допускается только для необязательного цвета.
width: int, по умолчанию 1. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().

Результат

Layer. Добавляет ломаную минимум из двух точек с цветом и шириной контура.

Права

Ошибки

KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

result = canvas.line("background", [(0, 0), (100, 50), (20, 80)], "#a78bfa")

polygon

Добавляет многоугольник минимум из трёх точек.

def polygon(id: str, points: list, **style: JSON) -> Layer: ...

Аргументы

id: str, обязательный. Уникальный во всей сцене ID слоя, от 1 до 128 символов.
points: list, обязательный. Координаты точек. Для line от 2 до 64, polygon от 3 до 64; значения от -4096 до 4096.
style: JSON, произвольные именованные аргументы. Именованные свойства выбранного слоя: допустимые поля и пределы приведены в IMAGE_GENERATOR.md. Свойства другого типа слоя отклоняются при build().

Результат

Layer. Добавляет многоугольник минимум из трёх точек.

Права

Ошибки

KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

result = canvas.polygon("background", [(0, 0), (100, 50), (20, 80)], fill="#a78bfa")

get

Ищет слой по ID, включая вложенные группы, и возвращает объект слоя.

def get(id: str) -> Layer: ...

Аргументы

id: str, обязательный. Уникальный во всей сцене ID слоя, от 1 до 128 символов.

Результат

Layer. Ищет слой по ID, включая вложенные группы, и возвращает объект слоя.

Права

Ошибки

KeyError(id): условие проверяется до продолжения операции.
KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

result = canvas.get("background")

remove

Удаляет перечисленные слои по ID.

def remove(*ids: str) -> Self: ...

Аргументы

ids: str, позиционные значения. Позиционные ID слоёв. Для order требуется каждый прямой дочерний ID ровно один раз.

Результат

Self. Тот же объект после успешной операции. Удаляет перечисленные слои по ID.

Права

Ошибки

KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

result = canvas.remove("background")

order

Переставляет все прямые дочерние слои в указанном порядке. Требуется перечислить каждый ID ровно один раз; частичная перестановка запрещена.

def order(*ids: str) -> Self: ...

Аргументы

ids: str, позиционные значения. Перечисли каждый прямой дочерний ID ровно один раз. Это полная перестановка, не частичная сортировка.

Результат

Self. Тот же объект после успешной операции. Переставляет все прямые дочерние слои в указанном порядке. Требуется перечислить каждый ID ровно один раз; частичная перестановка запрещена.

Права

Ошибки

ValueError('Specify every direct layer ID once'): условие проверяется до продолжения операции.
KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

canvas.order(*(layer["id"] for layer in canvas.layers))

grid

Раскладывает дочерние слои по сетке с заданными колонками, отступом и промежутком.

def grid(columns: int, gap: float = 0, padding: float = 0) -> Self: ...

Аргументы

columns: int, обязательный. Положительное число колонок сетки. Уменьшается до числа слоёв, если слоёв меньше.
gap: float, по умолчанию 0. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
padding: float, по умолчанию 0. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.

Результат

Self. Тот же объект после успешной операции. Раскладывает дочерние слои по сетке с заданными колонками, отступом и промежутком.

Права

Ошибки

ValueError('A positive column count is required'): условие проверяется до продолжения операции.
ValueError('The grid does not fit its bounds'): условие проверяется до продолжения операции.
KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

result = canvas.grid(2)

row

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

def row(gap: float = 0, padding: float = 0) -> Self: ...

Аргументы

gap: float, по умолчанию 0. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
padding: float, по умолчанию 0. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.

Результат

Self. Тот же объект после успешной операции. Размещает дочерние слои в одну строку.

Права

Ошибки

KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

result = canvas.row()

column

Размещает дочерние слои в один столбец.

def column(gap: float = 0, padding: float = 0) -> Self: ...

Аргументы

gap: float, по умолчанию 0. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.
padding: float, по умолчанию 0. Координата, отступ или угол в пикселях/градусах по выбранной операции. Все числа должны быть конечными.

Результат

Self. Тот же объект после успешной операции. Размещает дочерние слои в один столбец.

Права

Ошибки

KeyError для отсутствующего слоя; ValueError для дубликата, неверной перестановки или сетки, не помещающейся в контейнер.

Пример

result = canvas.column()