Model Annotation Plugin | Realsee Developer Platform

ModelMakerPlugin

Overview

The Model Annotation Plugin provides the following capabilities:

Provides annotation models in 3D space, including area annotation (prism) models, box models, and polygon (triangles) models.

External Demo

Open the Model Annotation demo to try the plugin outside this documentation page.

Installation

Choose either yarn or npm to install, as needed:

npm install @realsee/dnalogel

Plugin Methods

Initialization

import { Five } from '@realsee/five'
import { ModelMakerPlugin } from "@realsee/dnalogel";

const five = new Five({
    plugins: [
        [
            ModelMakerPlugin,
            'modelMakerPlugin', // custom plugin name
        ]
    ]
})

const plugin = five.plugins.modelMakerPlugin

Loading Data

Data structure declaration

// @include: main

// ---cut---
plugin.load(data)

Enable / Disable / Show / Hide the Plugin

// @include: main

// ---cut---
plugin.enable()

plugin.disable()

plugin.show()

plugin.hide()

Disposing the Plugin

// @include: main
// ---cut---
plugin.dispose()

Event Listening

Event types

// @include: main

// ---cut---
plugin.hooks.on('show', () => {
  console.log('plugin shown')
})

// @noErrors
plugin.hooks.on('')
//               ^|

Annotation Methods

Each annotation loaded into the plugin is an item.

Getting an item

Approach 1

// @include: main-plugin

// ---cut---
const item = plugin.getItemById(1)

Approach 2

// @include: main-plugin

// ---cut---
const item = plugin.items[0]

Enable / Disable / Show / Hide an item

// @include: main
// ---cut---
item.enable()

item.disable()

item.show()

item.hide()

Show / Hide an item's Model

// @include: main
// ---cut---
// show
item.model.visible = true 

// hide
item.model.visible = false

Show / Hide an item's Tag

// @include: main
// ---cut---
// show
item.tag?.show()

// hide
item.tag?.hide()

Customizing an item's Tag Style

// @include: main
// ---cut---
// Customize the box tag rendering
plugin.registerTagRenderer({ 'box': (container: HTMLElement, item: ModelMakerBaseItem) => {
  // example
  container.innerHTML = item.rawData.name

  // React is supported
  // ReactDOM.render(<div>{item.rawData.name}</div>, container)

  // Return a cleanup function
  return () => {
    container.innerHTML = ''
  }
}})

item Event Listening

Event types

// @include: main

// ---cut---
item.on('show', () => {
  console.log('item shown')
})

// @noErrors
item.on('')
//       ^|

Data Structures

Plugin Event Types

export interface EventMap {
  /** Plugin shown */
  show: () => void

  /** Plugin hidden */
  hide: () => void

  /** Plugin enabled */
  enable: () => void

  /** Plugin disabled */
  disable: () => void

  /** Data finished loading */
  dataLoaded: () => void

  /** Plugin disposed */
  dispose: () => void
}

item Event Types

export interface EventMap {
  /** item shown */
  show: () => void

  /** item hidden */
  hide: () => void

  /** item enabled */
  enable: () => void

  /** item disabled */
  disable: () => void

  /** item clicked */
  click: () => void
}

load Data

/** Data passed to load */
export interface ServerData {
  list: (ServerBoxItem | ServerTrianglesItem | ServerPrismItem)[]
}

export interface ServerBaseItem {
  /** Unique identifier */
  id?: number
  /** Tag name */
  name?: string
}

export interface ServerBoxItem extends ServerBaseItem {
  type: 'box'
  object_data: {
    /** Coordinates of one of the box's vertices */
    start: number[]
    /** Coordinates of the vertex diagonally opposite start */
    end: number[]
    /** Euler-angle rotation of the box, in [XYZ] order */
    rotation?: number[]
    /** Annotation color */
    color?: string
    /** Opacity */
    opacity?: number
  }
}

export interface ServerTrianglesItem extends ServerBaseItem {
  type: 'triangles'
  object_data: {
    /** Array of the polygon's vertex coordinates */
    points: number[][]
    /** Annotation color */
    color?: string
    /** Opacity */
    opacity?: number
  }
}

export interface ServerPrismItem extends ServerBaseItem {
  type: 'prism'
  object_data: {
    /** Array of 3D world-coordinate points defining the drawing plane */
    points: number[][]
    /** Floor height */
    height: number
    /** Floor the annotation belongs to */
    floorIndex?: number
    /** Manually set offset along the y-coordinate direction */
    fixedY?: number
    /** Manually set height correction */
    fixedHeight?: number
    /** Annotation color */
    color?: string
    /** Opacity */
    opacity?: number
  }
}