«Красный карандаш» — инструмент аннотирования моделей в браузере

В текущей версии C3D Web Vision стали доступны инструменты аннотирования. «Красный карандаш», или Markup, — это инструмент добавления замечаний или указаний в пространстве трехмерной модели. Он позволяет пользователю выделять какую-либо области модели с помощью геометрических примитивов. Мы предлагаем разработчикам различные возможности для управления и отображения дополнительного слоя информации поверх визуальной 3D-сцены.

Markup — это графический TypeScript-объект API C3D Web Vision, описанный следующим образом:

export type C3DViewMarkup = {
    type: C3DViewObjectTypes.Markup
    uuid?: string

    content: string
    position: {
        plane: C3DViewPlacement
        view: {
            positionDist: number
            targetDist: number
            projection: CameraProjection
        }
    }

    userData: C3DUserData
}

Поле content — это строка, которая должна содержать данные в формате svg. Данные описывают каждый примитив объекта Markup как соответствующий элемент svg, т. е., например, сегмент линии разметки преобразуется в линию svg и наоборот. Объект Markup может как записывать себя в эту строку, так и читать из нее.

Поле position — группа параметров для позиционирования объекта в сцене.

Ниже мы рассмотрим процесс создания объекта Markup.

Тип EditMarkupProcess (TypeScript):

export type EditMarkupProcess = {
    name: "EditMarkup",
    editing?: {
        uuid: string,
        cameraRestoringDuration?: number
    }
    options: MarkupOptions
    events: {
        onExit?: (uuid: string) => void
        onCameraProjectionChanged?: (prj: CameraProjection) => void
    }
}

Процесс позволяет пользователю построить следующие 2D-примитивы: отрезок, полилиния, окружность, овал, прямоугольник. Построенные примитивы хранятся в объекте Markup, который продолжает существовать до тех пор, пока пользователь не удалит его со сцены.

При построении примитив рисуется как фантом, а не добавляется мгновенно в конечный объект Markup. Это позволяет безопасно прервать построение, и примитив больше не будет существовать в сцене, поскольку процесс очищает фантомный объект. После каждого успешного построения процесс очищает фантом и добавляет построенный примитив в объект Markup.

Примитивы в объекте всегда рисуются в плоскости, параллельной плоскости экрана. Для этого Markup отключает все процессы камеры (сдвиг, масштабирование и т. д.). Пользователь не может изменить ее положение, пока процесс активен. Объект Markup зависит от параметров камеры, поэтому сохраняет их при каждом запуске в режиме создания и использует для восстановления при каждом запуске в режиме редактирования.

После остановки процесса Markup все процессы камеры возобновляются, и пользователь может продолжить дальнейшую работу.

Режимы

Процесс может работать в двух режимах: создание и редактирование. Режим создания определяет, что процесс создает новый объект Markup. Режим редактирования определяет, что процесс редактирует существующий объект. Очевидно, что процесс в таком режиме может быть успешно запущен только в том случае, если указанный объект существует в сцене.

Свойство ‘Editing’

Свойство ‘Editing’ позволяет запустить процесс Markup в режиме редактирования. Рассмотрим возможности этого свойства.

1. uuid — обязательное поле, необходимое для поиска объекта Markup с указанным uuid и подготовки его к редактированию. Если объект с uuid не найден, процесс выводит на консоль сообщение об ошибке и прекращает работу.
2. cameraRestoringDuration — необязательное поле, необходимое для установки длительности анимации восстановления параметров камеры.

По умолчанию, если свойство ‘Editing’ не задано, процесс запускается в режиме создания.

Дополнительные свойства

Свойства позволяют настроить параметры процесса:

• type задает тип примитива, который будет построен;
• pen позволяет настроить внешний вид примитивов (цвет и ширину линий);
• phantomPen позволяет настроить внешний вид фантомных примитивов.

Свойства процесса Markup (Typescript):

export type MarkupOptions = {
    type?: MarkupType
    pen?: {
        color?: C3DViewRGB
        width?: number
    }
    phantomPen?: {
        color?: C3DViewRGB
        width?: number
    }
}

Типы примитивов (type):

export enum MarkupType {
    LineSegment = 'lineSegment',
    Polyline = 'polyline',
    Rectangle = 'rect',
    Ellipse = 'ellipse',
    Circle = 'circle',
    Eraser = 'eraser',
    None = 'none'
}

События (Events)

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

Доступные события:

1. onExit(uuid) вызывается, когда пользователь останавливает процесс, и возвращает uuid созданного объекта Markup.
2. onCameraProjectionChanged(prj) вызывается, если процесс изменяет проекцию камеры при восстановлении ее параметров, и возвращает "новую" проекцию камеры prj. Это событие вызывается только в том случае, если процесс запущен в режиме редактирования и восстановленная проекция действительно отличается от текущей.

Запуск процесса Markup

Чтобы запустить процесс, необходимо вызвать команду RunProcessCommand с именем процесса EditMarkup.

Пример запуска процесса EditMarkup (TypeScript):

view.runCommand({
    name: "RunProcessCommand",
    process: {
        name: "EditMarkup",
        options: {
            type: MarkupType.LineSegment
        },
        events: {}
    }
})

или то же самое в режиме редактирования:

view.runCommand({
    name: "RunProcessCommand",
    process: {
        name: "EditMarkup",
        editing: {
            uuid: "..."
        },
        options: {
            type: MarkupType.LineSegment
        },
        events: {}
    }
})

Обновление процесса

Обновление позволяет изменить параметры, которые устанавливаются при запуске процесса. Общий тип команды обновления (TypeScript):

type UpdateProcess = {
    name: "UpdateProcessCommand"
    options: { name: "EditMarkup" } & MarkupOptions
}

Пример команды для обновления примитива для сборки (TypeScript):

view.runCommand({
    name: "UpdateProcessCommand",
    options: {
        name: "EditMarkup",
        type: MarkupType.LineSegment
    }
})

«Красный карандаш», или Markup, — не единственная команда аннотирования, в наборе инструментов C3D Web Vision еще есть комментарии (AddCommentProcess) и измерения, о которых мы расскажем в следующей статье.

В планах разработки добавление текстовых полей и геометрического примитива в виде облака.