Annotation Tables

In the SSTK, we try to have a small number of tables that can support different annotation tasks.

Scripts for creating the tables are in scripts/db/create_annotation_tables.sql. See Database setup for how to setup MySQL and run the scripts to setup the tables.

Main annotation table

The main annotation table consists of the following columns:

name	type	description
id	int(11)	ID of annotation record
appId	varchar(255)	ID of annotation app
sessionId	varchar(255)	ID of session
workerId	varchar(255)	Name of annotator
itemId	varchar(255)	ID of asset that was annotated
condition	varchar(255)	Annotation condition
data	mediumtext	String (JSON) storing annotation data
preview_data	mediumtext	Image (stored as base64 encoded string)
progress	float	Annotation progress
status	varchar(255)	Annotation status
notes	varchar(255)	Annotation notes
created_at	timestamp	When the annotation was created
updated_at	timestamp	When the annotation was updated
verified	boolean	Whether the annotation has been verified
imported	boolean	Whether the annotation was imported
code	varchar(255)	Code used for validation checks
task	varchar(255)	Name of task
type	varchar(255)	Type of annotation being performed (all records with the same type are expected to have data of the same format)
taskMode	varchar(255)	Whether the task is new (regardless of whether there are existing records) or fixup from existing

Annotation tools that store into the are typically append only so that a complete history of the annotation process can be retained. There is a current_annotations that shows the latest annotations (with the same fields, grouped over itemId,task,type).

Endpoints for retrieving and submitting to the main annotation table

url	description	method	parameters
/preview/:id	Return preview image for specified record id	GET
/submit	Submit (create a new) annotation	POST
/list	List annotation (from annotations table)	ALL
/list/latest	List latest annotations (from current_annotations table)	ALL
/list/latest/ids	List latest annotation ids (from current_annotations table)	ALL
/get/:id	Return annotation record for specified record id	ALL
/latest	Return latest annotation record	ALL
/edit	Updates existing annotation	ALL	action, data

Parameters for /list, /list/latest

name	description	example
format
extractData
$latest
$limit
$groupBy
$aggr
$or

In addition, the following fields can be specified as query filters: id, type, task, taskMode, appId, sessionId, workerId, itemId, condition, progress, status, notes, verified

Other tables

For some annotation tools, additional tables are designed so that those annotations are stored separately from the main SSTK annotations.

Semantic segmentation is stored in either in the main annotations table or in segment_annotations and part_annotations scripts/db/create_part_annotation_tables.sql. The separate tables allows for more fine grained querying of annotated parts but made the storing of annotations more complex.

For the original Scan Annotation Pipeline developed for ScanNet, we used segment_annotations to store the segmentation information. For the updated Multiscan Annotation Pipeline that had more granular annotation directly on triangles, the segmentation information is stored directly in the annotations table

Special parameters for /list, /list/latest

name	description	example
type	Specifying part or segment will query the part or segment tables
label