Area Annotation Plugin

npm install @realsee/dnalogel

import { AreaMakerPlugin } from "@realsee/dnalogel";

/** Plugin initialization parameters */
export interface Params {
  config?: Partial<Config>
  initialState?: Partial<State>
}

/** Plugin state */
export interface State extends BasePlugin.State {
  /** Whether the plugin is enabled */
  enabled: boolean
  /** Whether the plugin is visible as a whole */
  visible: boolean
}

/** Plugin configuration */
export interface Config {
  /** Whether the annotation model has depth testing enabled. This setting only affects the model and does not affect the display of the label.
   * @default true
   * @description When disabled, the annotation model will not be occluded by other models.
   */
  modelDepthTest: boolean
}

/** Plugin events */
export interface EventMap extends BasePlugin.EventMap<State, ServerData> {
  /** Callback when visible changes from false to true
   * @param event.userAction Whether this was triggered by a user action
   */
  show: (event: { userAction: boolean }) => void

  /** Callback when visible changes from true to false
   * @param event.userAction Whether this was triggered by a user action
   */
  hide: (event: { userAction: boolean }) => void

  /** Callback when enabled changes from false to true
   * @param event.userAction Whether this was triggered by a user action
   */
  enable: (event: { userAction: boolean }) => void

  /** Callback when enabled changes from true to false
   * @param event.userAction Whether this was triggered by a user action
   */
  disable: (event: { userAction: boolean }) => void

  /** Callback when config changes
   * @param event.prevConfig The config before the change
   * @param event.config The config after the change
   * @param event.userAction Whether this was triggered by a user action
   */
  configChange: (event: { prevConfig: Config; config: Config; userAction: boolean }) => void

  /** Callback when the plugin content is clicked
   * @param event.target The clicked annotation instance
   * @param event.intersectObjects The set of intersection points between the ray and the annotation model
   * @param event.wantsFiveTapGestureParams The callback parameters of Five's wantsFiveTapGesture
   * @returns <boolean> | <void> Returning false will prevent Five's wantsFiveTapGesture callback; any other return value is ignored
   */
  wantsTap: (event: { target: AreaMakerItem; intersectObjects: THREE.Intersection[] }) => boolean | void
}

/** Annotation instance events */
export type AreaMakerItemEventMap = {
  /** Callback when the annotation label is clicked
   * @param event.target The clicked annotation instance
   * @param event.nativeEvent The original MouseEvent of the click
   */
  tagClick: (event: { target: AreaMakerItem; nativeEvent: MouseEvent }) => void
}

/** Animation-related options */
export interface AnimeOptions {
  /** Animation duration, in milliseconds */
  duration?: number
}

export interface ShowHideOptions extends BasePlugin.BaseOptions {
  userAction: boolean
}

/** Version 1 data
 * @description Why do two versions of the data exist?
 * The current data already exists in production, and this version of the data currently has the following problems:
 * 1. It cannot describe curved lines.
 * 2. The data structure is not clear enough, and the data carries some product-level abstractions. For example, the annotation height is composed of the floor height plus a manually configured height correction.
 */
export interface ServerDataV1 {
  list: ServerAreaMakerItemV1[]
}

/** Version 2 data */
export interface ServerDataV2 {
  list: ServerAreaMakerItem[]
}

/** The data passed to load */
export type ServerData = ServerDataV1 | ServerDataV2

/** The data used by the plugin */
export type PluginData = ServerDataV2

export interface ServerAreaMakerItem {
  id: number | string
  /** Annotation name */
  name?: string
  /** The floor the annotation is on */
  floor_index: number
  /** Annotation object */
  object_data: {
    /** Shape of the annotation's bottom face, the result of THREE.Shape().toJSON() */
    shape: Record<string, any>
    /** The y coordinate of the annotation's bottom face */
    bottom_y: number
    /** Annotation height, i.e. the distance from the top of the annotation to its bottom. Must be positive, in meters */
    height: number
    /** Annotation color
     * @example "#ffffff"
     */
    color?: string
    /** Annotation opacity */
    opacity?: number
  }
}

export interface ServerAreaMakerItemV1 {
  id: number
  name: string
  object_data: {
    /** Set of 3D world coordinate points that define the drawn plane */
    points: number[][]
    /** Floor index */
    floorIndex: number
    /** Floor height */
    height: number
    /** Manually configured offset in the y-coordinate direction */
    fixedY: number
    /** Manually configured height correction */
    fixedHeight: number
    color: string // "#FFAB61"
    opacity?: number // Opacity
  }
}