RU codex docs document model v5

Модель документа CADYX v5

Документ содержит полный русский перевод исторического контракта v5. Для определения актуального поведения используйте v6–v12 и текущую реализацию.

Версионный контракт v5, не текущая схема. Здесь описано поведение, введённое в Document v5. Сейчас сохраняются документы v12, оболочка проекта остаётся v1. Актуальные ограничения сверяйте с картой документации и контрактами последующих версий, а не только с историческим описанием.

Оболочка проекта остаётся cadyx-project версии 1. Новые документы используют версию 5. При чтении документы v1–v4 обновляются в памяти, не меняя ID, объекты, ревизию, историю или файлы. Следующая успешная команда атомарно сохраняет обновлённый документ вместе с новой записью истории; неуспешная оставляет файл без изменений. Неизвестные версии отклоняются. Документ v1 поддерживал только тела и элементы. Старые хосты CADYX не могут читать документ v5: это изменение схемы вперёд, не обещание обратной совместимости. Последовательные миграции определены в cadyx/migrations.py; см. контракт миграций проекта.

Поддерживаемые объекты эскиза

Все объекты находятся в document.objects. ID — канонические типизированные UUID в нижнем регистре, уникальные в документе. В этой версии типы объектов: body, feature, sketch, point, line, circle, ellipse и constraint. Существующие отношения тел и элементов сохраняются.

Тип	Сохраняемые поля кроме id/type	Значение
sketch	name, plane	Имя длиной 1–120 символов; плоскость XY или XZ.
point	sketch_id, x, y, необязательный construction	Конечные координаты; конструкционная точка — опорная геометрия.
line	sketch_id, start_id, end_id, необязательные construction/extent	Ссылка на две точки; длина больше 1e-7; extent — segment (по умолчанию), infinite или centerline.
circle	sketch_id, center_id, radius, необязательные start_id/end_id/sweep_radians	Точная окружность или дуга с направленным размахом; концы дуги лежат на окружности и соответствуют размаху.
ellipse	sketch_id, center_x, center_y, major_radius, minor_radius, rotation_radians	Точный замкнутый аналитический эллипс; major_radius >= minor_radius > 1e-7, угол задан в радианах против часовой стрелки от оси X эскиза.
constraint	sketch_id, kind, references, value	Явный инвариант, проверяемый при каждой загрузке и команде.

Принадлежность задаётся через sketch_id, дублировать списки объектов в эскизе не нужно. Ссылки точки, линии и окружности должны указывать на объект нужного типа в том же эскизе. Изменение координат сохраняет ID и ссылки. Ссылок на временную топологию ядра нет. В эскизе XZ координаты x,y соответствуют глобальным X,Z; XY сохраняет своё отображение.

Конструкционные точки и линии остаются видимыми в сцене эскиза, но не включаются в замкнутые профили и траектории sweep. Бесконечная линия отображается сквозь viewport по двум определяющим точкам; осевые и конструкционные линии рисуются пунктиром. Необязательные поля сохраняют совместимость с документами, созданными до появления конструкционной геометрии.

Семантика ограничений

Ограничения только проверяют геометрию; они не решают систему и не перемещают элементы. Абсолютный допуск равен 1e-7 в единицах сохранённых координат; относительного допуска нет. CADYX пока не присваивает координатам физические единицы. Неподдерживаемое или нарушенное ограничение приводит к отказу, а не сохраняется как нерешённое состояние.

kind	Упорядоченные ссылки	Инвариант
horizontal	одна линия	Координаты Y концов равны.
vertical	одна линия	Координаты X концов равны.
coincident	ID двух различных точек	Евклидово расстояние равно нулю в пределах допуска.
distance	ID двух различных точек	Евклидово расстояние равно конечному неотрицательному значению.
radius	одна окружность	Радиус равен конечному положительному значению.

API команд

Обе существующие конечные точки команд Web и Agent API принимают эти команды под соответствующими блокировками изменения пользователя/агента. Результаты возвращаются в history_entry.result; все команды обычно возвращают зафиксированный документ.

• create_sketch: необязательные name (по умолчанию Sketch) и plane (по умолчанию XY). Возвращает sketch_id.
• add_sketch_point / add_sketch_construction_point: sketch_id, конечные x, y. Конструкционные точки не входят в профили и траектории sweep.
• add_sketch_segment, add_sketch_line, add_sketch_infinite_line, add_sketch_centerline, add_sketch_construction_line: sketch_id, различные конечные координаты start и end в виде {x, y}. Бесконечные линии и осевые линии не входят в профили и траектории; осевые и конструкционные линии отображаются пунктиром.
• add_sketch_element: sketch_id, element_type (point, line или circle) и поля этого элемента из таблицы. Возвращает object_id.
• add_sketch_polyline: sketch_id, точки points ({x, y}) и необязательный closed (по умолчанию false). Одной командой создаёт открытую цепь из 2–512 точек либо замкнутый многоугольник из 3–4096 точек. Расстояние между соседними точками, включая замыкающую пару многоугольника, должно превышать 1e-7. Возвращает созданные point_ids, line_ids и состояние closed. Это обычные точки и линии документа.
• add_sketch_line_chain: sketch_id и points ({x, y}). Создаёт открытую цепь из 2–512 точек; для замкнутого профиля используйте add_sketch_polyline.
• add_sketch_rectangle: sketch_id, координаты нижнего левого угла x, y, положительные width, height. Одной командой добавляет закрытый четырёхсторонний профиль как обычные точки и линии и возвращает их ID.
• add_sketch_rectangle_two_corners: sketch_id, противоположные углы x1, y1, x2, y2; длина каждой стороны должна превышать 1e-7. add_sketch_rectangle_center принимает center_x, center_y, положительные width, height.
• add_sketch_rectangle_three_points: points — координаты {x, y} трёх последовательных углов; соседние стороны проверяются на перпендикулярность. add_sketch_rotated_rectangle использует center_x, center_y, положительные width/height и angle_degrees.
• add_sketch_parallelogram: три последовательных неколлинеарных угла {x, y}.
• add_sketch_regular_polygon: center_x, center_y, целое side_count (3–512), положительный radius, необязательные rotation_degrees (по умолчанию 0) и radius_mode (inscribed по умолчанию либо circumscribed). Каждая команда строит замкнутый профиль из точек и линий и возвращает их ID.
• add_sketch_inscribed_polygon фиксирует описанный радиус, add_sketch_circumscribed_polygon — вписанный. У обеих одинаковые параметры центра, числа сторон и необязательного поворота.
• add_sketch_polygon_from_center принимает центр и координаты первой вершины; вершина задаёт описанный радиус и исходный поворот.
• add_sketch_circle: sketch_id, координаты центра x, y и положительный radius. Добавляет точку центра и окружность, возвращает point_id и circle_id.
• add_sketch_circle_diameter: sketch_id, центр x/y и положительный diameter. add_sketch_circle_two_points принимает first, second координатами {x, y} — противоположными концами диаметра. add_sketch_circle_three_points принимает три различные неколлинеарные точки. Каждая создаёт точную окружность и точку центра и возвращает point_id, circle_id.
• add_sketch_ellipse: sketch_id, координаты концов большой оси major_axis_start, major_axis_end и положительный minor_radius. Половина длины большой оси должна быть не меньше малого радиуса. Сохраняется один точный аналитический эллипс; возвращаются ellipse_id, центр и радиусы.
• add_sketch_ellipse_center: sketch_id, точка center, положительные major_radius, minor_radius, необязательный rotation_degrees (по умолчанию 0). Больший радиус должен быть не меньше малого. Возвращаются ID эллипса, центр и радиусы.
• add_sketch_ellipse_three_points: sketch_id, точки center, major_axis_endpoint, minor_axis_endpoint. Векторы от центра к двум концам должны быть перпендикулярны с относительным допуском 1e-7. Их длины задают радиусы; большой должен быть не меньше малого. Сохраняется точный аналитический эллипс.
• add_sketch_circle_tangent_to_line: sketch_id, line_id того же эскиза, tangent_point ({x, y}), положительный radius, необязательный side (1 по умолчанию или -1 относительно направления линии). Точка касания должна лежать на конечном отрезке либо на опорной прямой бесконечной линии. Центр точной окружности смещается на заданный радиус по выбранной нормали линии.
• add_sketch_circle_tangent_to_two_lines: sketch_id, различные first_line_id, second_line_id одного эскиза, положительный radius и необязательные first_side/second_side (каждый по умолчанию 1 либо -1 относительно направления линии). Пара сторон выбирает одно из четырёх решений по биссектрисам. Параллельные линии отклоняются; точки касания должны лежать в пределах конечных отрезков, для бесконечных линий используется вся опорная прямая. Возвращает окружность и точные координаты обеих точек касания.
• add_sketch_circle_tangent_to_three_lines: sketch_id и ID трёх различных линий того же эскиза; необязательные first_side, second_side, third_side (каждый по умолчанию 1 либо -1 относительно направления соответствующей линии). Совместное смещение трёх линий вычисляет центр и положительный радиус. Вырожденные сочетания сторон отклоняются; точки касания должны лежать на конечных отрезках. Возвращаются найденный радиус и все точки касания.
• add_sketch_arc_center: sketch_id, точки center, start, end, необязательный логический clockwise (по умолчанию false). Начало и конец должны лежать на одной окружности и отличаться друг от друга и от центра. Создаётся точная дуга с направлением; по умолчанию обход против часовой стрелки.
• add_sketch_arc_three_points: точки start, through, end, все различны и неколлинеарны. Команда находит единственную описанную окружность и знаковый размах через through; возвращаются точная дуга, центр и радиус.
• add_sketch_arc_start_center_end: геометрически эквивалентна add_sketch_arc_center, но порядок входных координат — start, center, end; необязательный clockwise выбирает направление.
• add_sketch_arc_radius: sketch_id, start, end, положительный radius; расстояние концов не может превышать диаметр. large_arc (по умолчанию false) выбирает малую/большую дугу, clockwise (по умолчанию false) — знак направления.
• add_sketch_arc_tangent: sketch_id, line_id того же эскиза, tangent_point, положительный radius, знаковый sweep_degrees строго между -360° и 360°, кроме нуля. side (по умолчанию 1 либо -1) задаёт сторону направленной линии для центра окружности. Точка касания должна лежать на отрезке либо на опорной прямой бесконечной линии. Дуга начинается в точке касания, её начальная касательная параллельна выбранной линии.
• add_sketch_rounded_rectangle: sketch_id, левый нижний угол x,y, положительные width,height, положительный corner_radius, меньший половины обеих сторон. Создаёт точные четверти окружностей и касательные отрезки; при извлечении профиля дуги дискретизируются шагом не больше 2.8125°.
• mirror_sketch_elements: sketch_id, непустые object_ids, axis_start и axis_end ({x, y}). Отражает выбранные точки, линии, окружности и эллипсы относительно произвольной оси эскиза; концы оси должны быть дальше 1e-7 друг от друга. Для линии/окружности копируются зависимости-концы/центр, копиям назначаются новые ссылки на точки. Эллипсы отражаются аналитически. Ограничения не копируются. Возвращаются ID исходного замыкания зависимостей и созданных точек, линий, окружностей, эллипсов и объектов.
• pattern_sketch_elements: sketch_id, непустые object_ids, режим linear или circular и count от 2 до 64 вместе с исходным экземпляром. В линейном режиме задаются offset_x/offset_y на экземпляр; в круговом — center_x, center_y, angle_step_degrees. Копируется то же замыкание зависимостей точек/линий/окружностей, что при зеркальном отражении; эллипсы преобразуются аналитически. Ограничения не копируются. Линейное смещение должно превышать 1e-7. Повторные круговые положения и результат больше 4096 созданных объектов отклоняются. Ответ группирует ID по типу и сообщает исходное замыкание и число экземпляров.

Команды создания, ограничения и изменения/удаления эскизов, импорт STEP и инженерный профиль описаны выше. Ниже переведены эскизные операции создания твёрдого тела.

• add_sketch_constraint: sketch_id, kind, упорядоченные references и value для расстояния/радиуса. Возвращает constraint_id.
• update_sketch_elements: непустой список updates формата {object_id, changes}. Для точек доступны x/y, для окружностей — radius. На каждый ID допускается одно изменение; нельзя менять владельца или ссылки. Весь набор проверяется совместно, поэтому несколько ограниченных точек можно переместить в одной атомарной команде. Возвращает object_ids.
• remove_sketch_object: object_id. Каскадного удаления нет: объект, на который ссылаются, удалить нельзя. В подходящем порядке удаляйте ограничения, линии/окружности, точки и затем эскиз. Возвращает object_id.
• import_step: параметр file задаёт прямой файл .step/.stp из текущего каталога проекта CADYX; необязательный name переопределяет имя тела. OCCT импортирует одно твёрдое тело и сохраняет редактируемую B-rep в документе. В ответе возвращаются ID тела и элемента, SHA-256 и размер источника в байтах, а также метрики геометрии. Исходный файл сохраняется; выходить за пределы каталога текущего проекта нельзя.

Пример: создать эскиз, добавить точки (0, 0) и (3, 0), создать линию по возвращённым ID точек, затем добавить горизонтальное ограничение по ID линии. Если изменить только Y второй точки на 1, команда отклоняется: ревизия, история и сохранённые байты не меняются. Если в одном пакете задать Y обеих точек равной 1, команда проходит, все ID и ссылки сохраняются.

Инженерные профили

add_sketch_involute_gear принимает пустой эскиз XY в sketch_id, положительный module, tooth_count от 3 до 128, pressure_angle_degrees от 5 до 45° (по умолчанию 20°), необязательные center_x, center_y, rotation_degrees и неотрицательный backlash, меньший половины кругового шага. Минимальное число зубьев проверяется по пределу подрезания рейкой для выбранного угла давления.

Команда создаёт замкнутый многоугольник из обычных точек и линий эскиза, возвращает рассчитанные делительный, основной, вершинный и корневой радиусы в gear_parameters. Модель — внешнее прямозубое колесо без смещения: d=mz, db=d cos(alpha), da=m(z+2), df=m(z-2.5). Для пары колёс межосевое расстояние равно m(z1+z2)/2, фаза сдвинута на половину углового шага зуба.

Боковые поверхности зуба выбираются из кривой эвольвенты в 12 точках по углу раскатывания; поэтому сохранённый эскиз является ломаной, не аналитической кривой и не связанным параметрическим элементом шестерни. Смещение исходного профиля, внутренние и косозубые колёса и корневые галтели, построенные режущим инструментом, не представлены.

create_metric_thread принимает положительные major_diameter, pitch, length (от одного до 64 шагов включительно), необязательный handedness (right по умолчанию или left) и необязательный name. Создаёт одно редактируемое твёрдое тело OCCT с однозаходной наружной ISO-метрической резьбой 60°, обрезает его от Z=0 на заданную длину и сохраняет дескриптор геометрии metric_thread со связанным элементом.

Для основного наружного профиля малый диаметр равен d3 = d - 1.226869P; округлённый корень приближён формулой R = sqrt(3)P/12 восемью сегментами на угол сечения. set_parameter может менять major_diameter, pitch, length, handedness; каждое изменение атомарно перестраивает B-rep. Внутренние резьбы, несколько заходов, классы допусков и сбеги резьбы не моделируются. Документы CADYX не задают физических единиц: модуль, диаметр и шаг выражены в координатных единицах документа.

Эти возможности используют существующий контракт объектов и элементов документа v3 и не требуют миграции схемы. Геометрия колеса остаётся обычной редактируемой геометрией эскиза, параметры резьбы хранятся в элементе. Формулы: ISO 724:2023, геометрия прямозубого колеса.

Эскизные элементы твёрдого тела

extrude_sketch принимает sketch_id, положительную depth, необязательный name и логический centered. Центрированное выдавливание распространяется поровну по обе стороны плоскости эскиза. Иначе начинается в плоскости и направлено вдоль её положительной нормали. Замкнутый контур XY выдавливается вдоль глобальной Z, XZ — вдоль глобальной Y.

revolve_sketch принимает sketch_id, необязательный angle_degrees (по умолчанию 360°, диапазон больше 0 и до 360° включительно) и необязательный name. Команда вращает один замкнутый профиль XZ вокруг глобальной Z. Для построения тела OCCT профиль должен находиться по одну сторону оси и касаться её.

Для профиля выдавливания можно использовать эскиз с одной окружностью или эллипсом; каждый дискретизируется в многоугольник из 128 рёбер. Полные эллипсы остаются точными в эскизе и дискретизируются только для профильных операций. Линейные профили могут содержать 3–4096 рёбер. Каждая операция принимает один контур; отверстия и многоконтурные профили не поддерживаются.

Команда сохраняет дескриптор OCCT B-rep и элемент со ссылкой на исходный эскиз и параметр операции. Изменение исходных точек перестраивает связанное тело той же атомарной командой. set_parameter может менять глубину выдавливания, угол вращения, радиус sweep и радиус fillet. Удаление эскиза, использованного элементом твёрдого тела, отклоняется.

Ограничения профиля только проверяют заданную геометрию и не решают её и не перемещают элементы. Адаптер OCCT перестраивает и проверяет каждое сохранённое тело, а треугольники viewport получает из B-rep. Это твёрдые тела, не импортированные треугольные сетки.

replace_sketch_profile заменяет цикл точек/линий выбранного эскиза и атомарно перестраивает его зависимые профильные элементы. Принимает sketch_id и от 3 до 4096 конечных точек {x, y}; эскизы с окружностями или ограничениями отклоняются. Изменение эскиза также перестраивает последующие зависимые твёрдые тела.

replace_sketch_path заменяет эскиз из точек и линий одной открытой связной цепью. Принимает sketch_id и 3–512 конечных точек {x, y}, создаёт линию между соседними точками и анимирует путь при рисовании. В эскизе пути запрещены ветви, циклы, окружности и ограничения.

sweep_sketch принимает sketch_id, положительный радиус круглого сечения radius и необязательный name. Окружность протягивается вдоль открытой цепочки линий эскиза, подгоняя направляющую C2 B-spline к допуску аппроксимации OCCT. Поддерживаются траектории XY/XZ; траектория XZ вертикальна относительно глобальной Z. Результат swept_pipe — замкнутое твёрдое тело OCCT, связанное с исходным эскизом; изменение точек траектории или радиуса перестраивает результат. Во время анимации труба постепенно проявляется вдоль пути.

fuse_bodies принимает base_body_id, tool_body_id и необязательный name для двух пересекающихся твёрдых OCCT B-rep. Нативное булево объединение должно сформировать одно связное корректное тело. Поддерживаются тела из профилей, трубы sweep и предыдущих операций fuse/fillet; импортированные треугольные сетки не являются входами B-rep. Дескриптор fused_solids сохраняет геометрические дескрипторы обоих источников и перестраивается при изменении любого из них. Поддерживаются старые дескрипторы fused_profiles.

cut_bodies принимает base_body_id, tool_body_id и необязательный name. Булева операция OCCT вычитает инструмент из основы; в результате должно остаться одно корректное тело положительного объёма. Два исходных дескриптора редактируемой B-rep сохраняются в графе элемента cut_solids; при изменении любого источника результат перестраивается. Если инструмент не удаляет материал либо делит основу на несколько тел, команда атомарно отклоняется. Треугольные сетки не являются входами B-rep.

GET /api/v1/agent/projects/{project_id}/topology?body_id=... инспектирует уникальные актуальные рёбра B-rep тела для выбора в последующих операциях. Каждое ребро имеет index обхода, длину, центр масс и тип кривой. Индексы соответствуют только текущей топологии и не являются постоянными именами; после любого вышестоящего изменения снова инспектируйте топологию перед выбором.

fillet_edges принимает body_id, 1–128 различных edge_indices, положительный radius и необязательный name. Создаёт новое тело со скруглением перекатываемой кромки OCCT — например, для обода/основания кружки либо соединения с уже объединённой ручкой. set_parameter изменяет радиус. Дескриптор filleted_solid хранит исходную B-rep, выбранные индексы текущих рёбер и радиус. Если вышестоящее изменение меняет топологию или делает радиус невозможным, перестроение зависимости атомарно отклоняется, сохранённая модель остаётся неизменной.

Эскизы sweep, использованные элементом, и все неактивные эскизы скрыты в пользовательском дереве и viewport. Исходные тела fillet/fuse остаются в истории для редактирования, но скрыты из viewport и дерева объектов; отображаются только ещё не потреблённые результаты. Изменение эскиза исходника перестраивает зависимые sweep, fillet и fuse по порядку документа.

Импорт STEP и редактируемые B-rep

import_step читает непосредственный файл .step или .stp из каталога текущего проекта через STEPControl_Reader OCCT. Принимается одно твёрдое тело; сериализация OCCT B-rep сохраняется в дескрипторе тела imported_brep. Треугольники viewport служат лишь триангуляцией для отображения. Элемент проекта сохраняет имя исходного файла, SHA-256, размер в байтах и метрики исходной геометрии. Сохранённая B-rep самодостаточна и остаётся пригодной, если исходник позднее переместят. Размер источника и сериализованной B-rep ограничен 64 МиБ каждый.

Метрики источника включают объём, площадь поверхности, координаты границ, число уникальных тел/граней/рёбер/вершин, валидность B-rep и признак того, исправил ли OCCT форму в пределах точности 1e-7 и максимального допуска 1e-5 единиц модели. CADYX проверяет обратное преобразование сериализованной B-rep по этим метрикам. Если OCCT не может исправить импортированное тело, CADYX сохраняет точную переданную форму и устанавливает brep_valid: false, не меняя её молча. Такое тело можно отобразить, если OCCT способен его триангулировать, но булевы операции и fillet требуют валидной B-rep и могут отклонить его.

resize_imported_thread принимает body_id импортированного тела, границы резьбового участка x_start/x_end, его major_diameter, положительный diameter_delta и необязательные axis_origin_y/axis_origin_z для оси резьбы, параллельной глобальной X. Выбранный участок должен содержать только резьбу. При необходимости OCCT исправляет самопересекающиеся проволочные контуры некорректных плоских граней; затем вырезает интервал, радиально масштабирует его вокруг заданной оси и объединяет с исходным телом. Результат должен быть одним корректным замкнутым телом; исходное сохраняется в истории элемента и скрывается в viewport.

transform_imported_brep принимает импортированный body_id, трёхкомпонентную rotation_axis, значение angle_degrees и трёхкомпонентный translation. Тело поворачивается вокруг глобального начала координат, переносится и сохраняется новым редактируемым элементом импортированной B-rep. Жёсткие преобразования сохраняют исходный объём и топологию; потреблённые исходные тела остаются в истории.

Проверяемая передача CAD

export_brep выполняется через существующую конечную точку команд с блокировкой и принимает существующее корректное замкнутое однотельное тело OCCT B-rep. Треугольные сетки и некорректные импортированные B-rep отклоняются. В конверте запроса обязателен expected_revision, чтобы связать каждый артефакт с точным сохранённым состоянием модели:

{
  "lease_id": "...",
  "expected_revision": 12,
  "command": {
    "type": "export_brep",
    "body_id": "body:...",
    "include_stl": true,
    "linear_deflection": 0.1,
    "angular_deflection": 0.5
  }
}

STEP всегда записывается как аналитическая модель STEP OCCT и до публикации импортируется повторно. Проверка должна вернуть одно корректное тело и сохранить исходный объём с относительным/абсолютным допусками 1e-8/1e-7 единиц модели; все шесть границ должны сохраниться с допуском 1e-6. STEP больше 64 МиБ отклоняется, поскольку не пройдёт существующее ограничение импорта STEP.

При include_stl: true CADYX создаёт бинарный STL с линейным и угловым отклонениями OCCT. Значения по умолчанию — 0.1 единицы модели и 0.5 радиана; допустимый минимум линейного отклонения 0.001 единицы модели, угловое — 0.01–1.0 радиан. STL также ограничен 64 МиБ. Перед публикацией CADYX проверяет водонепроницаемость и согласованность ориентации сериализованной сетки, вычисляет знаковый объём и относительную ошибку по сравнению с точной B-rep, затем сравнивает до 64 равномерно распределённых центроидов треугольников с точными гранями B-rep. В манифесте одностороннее отклонение поверхности помечается как выборочное — это не исчерпывающее геометрическое доказательство. STEP остаётся точным авторитетным результатом; ни один формат не доказывает физическую посадку, прочность или пригодность к печати.

STEP, необязательный STL и манифест *.cad-delivery.json создаются непосредственно в каталоге текущего проекта. Имена включают очищенное от небезопасных символов имя тела, ревизию источника, идентификатор геометрии и хеш содержимого результата. Каждый файл атомарно создаётся без перезаписи существующего: побайтно идентичный артефакт переиспользуется, а конфликт имени при различном содержимом отклоняет команду. Все экспорты и проверки завершаются до публикации; манифест записывается последним.

В манифесте указываются исходные тело/ревизия и канонический SHA-256 геометрии, версия OCCT, имена/хеши/размеры файлов, метрики источника и повторно импортированного STEP, допуски и необязательные проверки/измерения STL. Команда экспорта попадает в историю и увеличивает ревизию команды, но source.document_revision в манифесте остаётся ревизией, из которой получено тело. Файлы можно перечислить и скачать существующими API проекта.

API эскизов — продолжение

• add_sketch_arc_center: sketch_id, координаты center, start, end и необязательный логический clockwise (по умолчанию false). Начало и конец должны лежать на одной окружности и отличаться друг от друга и от центра. Создаётся точная дуга; по умолчанию обход против часовой стрелки.
• add_sketch_arc_three_points: координаты start, through, end; все точки должны быть различны и неколлинеарны. Команда находит единственную описанную окружность и выбирает знаковый размах через through, возвращая точную дугу, центр и радиус.
• add_sketch_arc_start_center_end: та же точная геометрия, что у add_sketch_arc_center, но порядок входов — start, center, end; необязательный clockwise выбирает направление обхода.
• add_sketch_arc_radius: sketch_id, start, end, положительный radius; расстояние между концами не может превышать диаметр. large_arc (по умолчанию false) выбирает малую или большую дугу, clockwise (по умолчанию false) задаёт её направление.
• add_sketch_arc_tangent: sketch_id, line_id того же эскиза, tangent_point, положительный radius, знаковый sweep_degrees строго между -360° и 360° (кроме нуля). side (по умолчанию 1 либо -1) выбирает сторону направленной линии для центра. Точка касания должна лежать на отрезке или на опорной прямой бесконечной линии. Дуга начинается в точке касания, её начальная касательная параллельна выбранной линии.
• add_sketch_rounded_rectangle: sketch_id, нижний левый угол x,y, положительные width,height и corner_radius, меньший половины обеих сторон. Создаёт точные четверти окружностей и касательные отрезки; при извлечении профиля дуги дискретизируются с шагом не больше 2.8125°.
• mirror_sketch_elements: sketch_id, непустые object_ids, точки axis_start/axis_end ({x, y}). Отражает выбранные точки, линии, окружности и эллипсы относительно произвольной оси в плоскости эскиза; ось должна иметь длину больше 1e-7. При выборе линии/окружности также копируются зависимые точки концов/центра с новыми ссылками. Эллипсы отражаются аналитически. Ограничения не копируются. Ответ включает исходное замыкание ссылок и ID созданных точек, линий, окружностей, эллипсов и объектов.
• pattern_sketch_elements: sketch_id, непустые object_ids, mode (linear/circular), count от 2 до 64 включительно вместе с исходным экземпляром. В режиме linear задаются offset_x/offset_y на экземпляр; в circular — center_x, center_y, angle_step_degrees. Копируется замыкание зависимостей точек/линий/окружностей; эллипсы преобразуются аналитически. Ограничения не копируются. Линейное смещение больше 1e-7; повторные круговые положения и результат свыше 4096 созданных объектов отклоняются. Ответ группирует ID по типу, сообщает исходное замыкание и общее число экземпляров.
• add_sketch_constraint: sketch_id, kind, упорядоченные references, value для расстояния/радиуса. Возвращает constraint_id.
• update_sketch_elements: непустой updates со значениями {object_id, changes}. Для точки допускаются x/y, для окружности — radius. На один ID допускается одно обновление; менять владельца и ссылки нельзя. Проверяется весь пакет целиком, поэтому связанные ограничения могут допустить совместное изменение точек одной атомарной командой. Возвращает object_ids.
• remove_sketch_object: object_id. Каскадного удаления нет; объект, на который ссылаются, удалить нельзя. При необходимости удаляйте сначала ограничения, затем линии/окружности, точки и эскиз. Возвращает object_id.
• import_step: file указывает непосредственный файл .step/.stp в каталоге текущего проекта CADYX; необязательный name задаёт имя тела. Через OCCT импортируется одно тело, редактируемая B-rep сохраняется в документе. Возвращаются ID тела/элемента, SHA-256 и длина исходника в байтах, метрики геометрии. Источник сохраняется, путь за пределы текущего каталога проекта недопустим.

Пример: создайте эскиз, добавьте точки (0, 0) и (3, 0), создайте линию по их ID и добавьте горизонтальное ограничение на ID линии. Если изменить только Y второй точки на 1, команда отклоняется без изменения ревизии, истории или сохранённых байтов. Если изменить координату Y обеих точек на 1 в одном пакете, команда пройдёт, сохранив ID и ссылки.

Импорт сканов и редактируемые треугольные сетки

import_scan читает один непосредственный PLY-файл из каталога workspace, сохраняет исходник и создаёт тело с треугольной сеткой cadyx-mesh-v1 и элементом reconstruct_scan. Команда отправляется существующей конечной точке Web-команд или Agent API под блокировкой изменения проекта:

{
  "type": "import_scan",
  "folder": "kobras1backcover",
  "file": "Merge_02_pc.ply",
  "name": "Сканированная крышка",
  "parameters": {
    "voxel_size": 0.75,
    "target_triangles": 30000,
    "outlier_neighbors": 20,
    "outlier_std_ratio": 2.0,
    "poisson_depth": 8
  }
}

folder и file должны разрешаться в непосредственный обычный .ply проекта; обход каталогов и символьные ссылки отклоняются. Команда сохраняет относительный путь и SHA-256 источника в элементе. При изменении параметра обработки исходник считывается заново; если его содержимое изменилось, команда отклоняется.

Исходный PLY доступен только для чтения. Восстановленная сетка самодостаточно хранится в project.json и остаётся доступна, даже если исходный файл станет недоступным. CADYX записывает обработанную сетку бинарным little-endian PLY рядом с исходником. Имя результата адресуется по содержимому: {source-stem}.cadyx-{mesh-sha256-prefix}.ply. Элемент хранит относительный путь, хеш и размер файла. Публикация атомарна и не заменяет файл: байт-в-байт идентичный результат используется повторно, конфликт отклоняет команду. Временные файлы скрыты в списке workspace.

Поддерживаются как исходные треугольные сетки PLY, так и облака точек. Сетки очищаются и упрощаются; облака точек прореживаются вокселями, очищаются от статистических выбросов, получают согласованно ориентированные нормали и восстанавливаются методом screened Poisson. Результат — редактируемая треугольная сетка, не OCCT B-rep. Упакованные вершины float32 и индексы треугольников uint32 сжимаются, ограничиваются по объёму и проверяются по контрольной сумме в GeometryKernel; история команды хранит только ID, параметры и количество элементов, а не вторую копию сетки.

Параметры по умолчанию: voxel_size=0.75 в координатных единицах источника, target_triangles=30000, outlier_neighbors=20, outlier_std_ratio=2.0, poisson_depth=8. voxel_size и target_triangles относятся к обоим типам входа; параметры удаления выбросов и Poisson — только к облаку точек. Команда set_scan_parameter принимает feature_id, name, value и перестраивает геометрию из неизменённого источника.

Пределы параметров: размер вокселя 0.00001–10000, число треугольников 100–100000, число соседей для фильтра выбросов 4–128, отношение стандартных отклонений 0.1–5, глубина Poisson 5–9. CPU-обработчик использует максимум четыре потока и уменьшает облако не более чем до 100000 точек; входной PLY ограничен размером 512 МиБ, 2 млн вершин и 5 млн граней. Обработчик — SDK Open3D 0.20.0 для CPU, закреплённый SHA-256 и доступный через нативный мост C ABI; он не зависит от Python ABI CADYX. См. настройку среды.

По мере проверки источника, очистки сетки или облака, реконструкции, валидации, публикации бокового файла и сохранения проекта Core отправляет снимки SSE agent.activity. Инспекции модели и запросы viewport через Agent Runtime/API записываются в тот же поток. Read-only-браузер анимирует изменения модели и показывает один компактный статус действия/результата; этапы операции и сырой журнал команд не выводятся. GET /api/v1/projects/{id}/activity и маршрут Agent API возвращают последние 128 снимков операций из текущего процесса, чтобы открытый или повторно загруженный браузер продолжил отображать работу. Состояние активности, как и SSE, существует только в памяти процесса.

Инспекция в браузере и редактирование через Agent API

Браузер — подробный просмотрщик, доступный только для чтения. По умолчанию общий viewport развёрнут на всё окно; дерево модели и свойства находятся в свёрнутых панелях. Дерево отображает тела и их элементы, а также только текущий эскиз в режиме редактирования с точками, линиями, окружностями, эллипсами и ограничениями. Неактивные эскизы и эскизы, потреблённые элементами твёрдого тела, скрыты в дереве и viewport.

Viewport показывает поддерживаемые тела и плавно анимирует изменения активного эскиза, профильных элементов, sweep, fuse и fillet. Управление видом не меняет состояние документа.

Агенты создают проекты и редактируют модели через Agent API под блокировкой агента. Если браузер опубликовал актуальный кадр, агент может получить точный PNG основного viewport по GET /api/v1/agent/projects/{id}/viewport.png; иначе API использует автономный серверный рендеринг. Обычный viewport API также доступен и возвращает сцену в JSON.

Перечисленные команды создают коробки и эскизы XY/XZ; добавляют эскизную геометрию и проверяемые ограничения; выдавливают/вращают замкнутые профили; протягивают круговое сечение по открытому эскизу; объединяют твёрдые B-rep; скругляют выбранные рёбра B-rep; изменяют параметры элементов и эскизные объекты; удаляют неиспользуемые объекты эскизов.

Каждая команда использует общую Command System; перед атомарным сохранением проверяется весь документ. Ограничения только проверяют введённую геометрию — они не решают систему и не перемещают объекты. В браузере нет элементов управления созданием, редактированием и удалением проектов или моделей.