Skip to content

Latest commit

 

History

History
143 lines (106 loc) · 7.29 KB

README.md

File metadata and controls

143 lines (106 loc) · 7.29 KB
Raw

Drawing Tools

This directory holds React components and MobX State Tree models for the drawing tools that are available to the drawing task.

Experimental tools should be added to drawingTools/experimental.

React Components

import { Point } from '@plugins/drawingTools/components'

A React component for a mark takes a Mark model and renders it as SVG. The basic shape is:

const MarkComponent = mark.toolComponent
<MarkComponent active mark={mark} scale={scale} onFinish={onFinish} />
  • mark is the mark model to render.
  • scale is the linear scale of the subject image (clientWidth / naturalWidth).
  • active is a boolean attribute indicating whether the mark is currently editable.
  • onFinish is a callback that should be called when initial creation of the mark is complete. It resets the drawing canvas and tells it to start listening to clicks to create new marks again.

Tool models

import { PointTool } from '@plugins/drawingTools/models/tools'

The base Tool model defines the following common properties and actions for all drawing tools.

  • color (string)
  • label (string)
  • max (number = Infinity)
  • min (number = 0)
  • details (array) An array of task definitions for this tool eg. a text task for a transcription line tool. Task definitions are in the same format as workflow task definitions and can be passed to Task models.
  • tasks (Map) A map of Tasks for the subtasks of this tool. Automatically generated from tool.details.
  • disabled (boolean) Read only. True if new marks cannot be created.
  • isComplete (boolean) Read only. True if all required marks have been made and all required mark tasks have been annotated.
  • createMark(snapshot) (Mark) Returns a new mark from the supplied snapshot, and stores it.
  • createTask(snapshot) (Task) Returns a new task from the supplied snapshot, and stores it.
  • deleteMark(mark) Removes the specified mark from this tool.

All tools should extend the Tool model by implementing the following:

  • marks: a map of mark types for this particular tool eg. types.map(Line) for the Line tool.
  • type: a string uniquely identifying this type of tool.
  • createMark(snapshot): an action which creates a new mark from the supplied snapshot, then stores it in self.marks.
  • handlePointerDown(event, mark): handle pointer down events when creating mark. event.x and event.y contain the pointer coordinates on the SVG canvas. Implement this action to handle custom mark validation for marks that require complex gestures to create.
  • handlePointerMove(event, mark): handle pointer move events when creating mark. event.x and event.y contain the pointer coordinates on the SVG canvas. Implement this action to handle custom mark validation for marks that require complex gestures to create.
  • handlePointerUp(event, mark): handle pointer up events when creating mark. event.x and event.y contain the pointer coordinates on the SVG canvas. Implement this action to handle custom mark validation for marks that require complex gestures to create.

Mark models

import { Point } from '@plugins/drawingTools/models/marks'

The base Mark model defines common properties and actions for all marks.

  • id (string) Mark identifier. Automatically generated when a mark is created by a tool.
  • annotations (Map) A map of annotations created on this mark by tool tasks.
  • frame (number = 0) The subject frame that this mark was made on.
  • toolIndex (number) The array index of the tool that created this mark.
  • isComplete (boolean) Read only. True if all required tasks have been annotated for this mark.
  • isValid (boolean) Read only. True if any required validations pass for this mark (eg. minimum length for a line.)
  • tasks (array) Read only. An array of any sub-tasks linked to this mark eg. a text task for a transcription line.
  • tool (Tool) Read only. A reference to the tool that created this mark.
  • videoTime (number = undefined) For certain drawing tools (e.g. Temporal Point), we need to know WHEN the mark was created. For other drawing tools, videoTime will always return undefined.
  • addAnnotation(task, value) Add value to the annotation for task, which should be a valid task for this mark.
  • setVideoTime(number) For most drawing tools, this does nothing. For certain drawing tools (e.g. Temporal Point), this function must be customised to set a time value for the mark.

All marks should extend the Mark model by implementing the following views and actions:

  • coords (Object { x, y }) Read only. Returns the { x, y } coords for this mark.
  • deleteButtonPosition(scale) (Object { x, y }) Given the image scale, return the { x, y } position for this mark's delete button.
  • toolComponent (React.Component) Read only. Returns the React component used to render this mark.
  • initialDrag({ x, y }) Called on drag when first creating the mark. { x, y } are the new position of the dragged pointer in the frame of the subject image.
  • initialPosition({ x, y }) Called on initial click/tap when creating the mark. { x, y } are the position of the pointer in the frame of the subject image.
  • move(difference) Called on drag when moving the mark. difference is the change in position since the last move: { x, y }.
  • setCoordinates(Object) Passes in a new set of coordinates for the current shape. The object passed in will depend on the type of shape being described (eg. { x1, y1, x2, y2 } for an SVG line.)

In addition, mark models should extend the base Mark model with any properties specific to the new shape. These mark properties will be passed to Panoptes as the annotation for this mark. Marks may specify the following properties, which have a special meaning when rendering marks.

  • angle (number) Rotation angle of the mark in degrees, measure clockwise from the positive x-axis.
  • x (number) x position of the mark's centre of rotation, in SVG coordinates relative to the subject image.
  • y (number) y position of the mark's centre of rotation, in SVG coordinates relative to the subject image.

Working with tools and marks

// Create a new drawing tool.
const tool = TranscriptionLine.create({
  color: 'green',
  label: 'Transcribe a line',
  type: 'transcriptionLine'
})

// Add a text task to a drawing tool.
// NB. This is done automatically by the DrawingTask model
// when a tool has tool.details defined.
tool.createTask({
  taskKey: 'T0.0.0',
  instruction: 'Transcribe the marked line.',
  required: 'true',
  type: 'text'
})

// draw some lines.

const line1 = tool.createMark({
  id: 'line1'
  x1: 10,
  y2: 10,
  x2: 200,
  y2: 10
})

const line2 = tool.createMark({
  id: 'line2'
  x1: 10,
  y2: 20,
  x2: 200,
  y2: 20
})

// render subtasks for a mark.

line1.tasks.map(task => renderTask(task))

// add some text to each drawn line.

const task = tool.tasks[0]

let annotation = line1.addAnnotation({ task })

annotation.update('Hello! This is the first line.')

annotation = line2.addAnnotation({ task })

annotation.update('This is the second line of text.')

// check if a line has been completed.

if ( line1.isComplete ) {
  …
}