Export Annotation Format
RedBrick AI exports annotations in a JSON structure, accompanied by NIfTI-1 masks for segmentations. All data will be exported within a folder named after your
project_id, with the following structure:project_id/
├── segmentations
│ ├── study01
│ │ └── series1.nii
│ └── study02
│ ├── series1.nii
│ └── series2.nii
└── tasks.json
The segmentation directory will contain a single sub-directory for each task in your export. The sub-directories will be named after the task
name. A single task (depending on whether it was single series or multi-series) can have one or more segmentations.The individual segmentation files will be in NIfTI-1 format and be named after the user-defined series name. If no series name is provided on upload, RedBrick will assign a unique name. Corresponding meta-data ex. category names will be provided in tasks.json.
There will be a single entry for each task in the items file. Please see the definition (typescript) of the JSON object below:
type Tasks = Task[];
// Single task on RedBrick can be single/multi-series
type Task = {
// Required on upload and export
name: string;
series: Series[];
// Task level annotation information
classification?: Classification;
// Not required on upload
taskId?: string;
currentStageName?: string;
createdBy?: string;
createdAt?: string;
updatedBy?: string;
updatedAt?: string;
// assign metadata to a Task
metaData?: { [key: string]: string }
// Prescribe task assignent
preAssign?: {
[stageName: string]: string
}
};
// A single series can be 2D, 3D, video etc.
type Series = {
items: string | string[];
name?: string;
segmentations?: string | string[];
segmentMap?: {
[instanceId: string]: number | string | string[] | {
category: number | string | string[];
attributes?: Attributes;
};
};
landmarks3d?: Landmarks3D[];
measurements?: (MeasureLength | MeasureAngle)[];
boundingBoxes?: BoundingBox[];
polygons?: Polygon[];
polylines?: Polyline[];
classifications?: Classification[];
instanceClassifications?: InstanceClassification[];
metaData?: { [key: string]: string };
};
// Label Types
type Landmarks3D = {
point: VoxelPoint;
category: string | string[];
attributes?: Attributes;
};
type MeasureLength = {
type: 'length';
point1: VoxelPoint;
point2: VoxelPoint;
absolutePoint1: WorldPoint;
absolutePoint2: WorldPoint;
normal: [number, number, number];
length: number;
category: string | string[];
attributes?: Attributes;
};
type MeasureAngle = {
type: 'angle';
point1: VoxelPoint;
point2: VoxelPoint;
vertex: VoxelPoint;
absolutePoint1: WorldPoint;
absolutePoint2: WorldPoint;
absoluteVertex: WorldPoint;
normal: [number, number, number];
angle: number;
category: string | string[];
attributes?: Attributes;
};
type BoundingBox = {
pointTopLeft: Point2D;
wNorm: number;
hNorm: number;
category: string | string[];
attributes?: Attributes;
// video meta-data
video?: VideoMetaData;
};
type Polygon = {
points: Point2D[];
category: string | string[];
attributes?: Attributes;
// video meta-data
video?: VideoMetaData;
};
type Polyline = {
points: Point2D[];
category: string | string[];
attributes?: Attributes;
// video meta-data
video?: VideoMetaData;
};
type Classification = {
category: string | string[];
// video meta-data
video?: VideoMetaData;
};
type InstanceClassification = {
fileIndex: number;
fileName?: string;
values: { [attributeName: string] : boolean};
}
type Attributes =
| { // Taxonomy V2 attributes
attrId?: number;
name?: string;
optionId?: number | number[];
value?: string | boolean | string[];
}[]
| { // Taxonomy V1 attributes
[attributeName: string]: string | boolean | string[];
};
type VideoMetaData = {
frameIndex: number;
trackId: string;
keyFrame: number;
endTrack: Boolean;
};
// i is rows, j is columns, k is slice
type VoxelPoint = {
i: number;
j: number;
k: number;
};
// The position of VoxelPoint in physical space (world coordinate) computed using the Image Plane Module
type WorldPoint = {
x: number;
y: number;
z: number;
};
type Point2D = {
xnorm: number;
ynorm: number;
};
The
Task object represents a single task on RedBrick AI. It contains task-level meta-data information about all the series within the task. A task can contain a single series or multiple series (ex. a full MRI study). A user-defined string is defined on upload, it is required to be unique across all tasks in your project. The
name is meant to be a human-readable string that can help identify tasks ex. you can set name of a task to patient/study01.A RedBrick AI generated a unique identifier for each task. This value will be provided on export.
The current stage this task is in is when it was exported.
The e-mail of the user who uploaded this task.
The datetime this task was created (uploaded).
The e-mail of the last user to make edits to this task.
The datetime this task was last edited.
Prescribe during upload who will get a task assigned to them. You can define the assignment for each stage of the workflow, for example, Label and Review,
{"Label": "[email protected]", "Review": "[email protected]"}.A list of attributes assigned to an entire task (or study, if the task encapsulates an entire study).
metaData?: { [key: string]: string }A list of key value pairs that can be affixed to a Task.
The
Series object has meta-data and annotations for a single series within a task. A series can represent a single MRI/CT series, a video, or a single 2D image. If a series has annotations, you can expect one or more of the label entries to be present i.e. segmentations, polygons etc.The items entry is a list of file paths that point to your data. Please have a look at the Items Listdocumentation to understand how to format for various modalities and series/study uploads.
An optional user-defined string, needs to be unique across all series. Individual series will be named after this value on the labeling tool. Exported segmentation files will also be named using this value. Using the Series Instance UID here is good practice.
A list of attributes assigned to a specific Series.
The
instanceClassifications object defines a series of boolean values that can be assigned to individual instances (e.g. frames in a video).metaData?: { [key: string]: string }A list of key value pairs that can be affixed to a Series.
Here are the definition for some common entries present in some/all label entries.
The class of your annotations. This value is part of your project taxonomy. If the class is nested,
category will be string[].Each annotation can have accompanying attributes, that are also defined in your project taxonomy.
attributeName is defined when creating your taxonomy. VoxelPoint represents a three-dimensional point in image space, where i and j are columns and rows, and k is the slice number. WorldPoint represents a three-dimensional point in physical space/world coordinates. The world coordinates are calculated using VoxelPoint and the Image Plane Module.Point2D represents a two dimensional point. This is used to define annotation types on 2D data. xnorm has been normalized by image width, hnorm has been normalized by image height.fileIndex is an integer that corresponds to a specific frame in a video series.fileName represents the name given to an image or specific frame in a video series.This specifies which frame in a video sequence the annotation was created.
A unique string that identifies distinct object tracks in a video sequence.
If true, this annotation was manually added on a particular video sequence. If false, this annotation is a result of linear interpolation.
If true, the annotation is the last annotation for a particular video track segment.
A list of file paths of segmentation files for this series. Either a single
.nii file, or multiple .nii files containing different instances.A mapping between segmentation instance id, your taxonomy category name, and any accompanying attributes. The mapping will apply only to the current series, and instance ids must be unique across all series in a task - this is useful for instance segmentation.
Represents a two-dimensional bounding box
The location of the top-left point of the bounding box.
The width and height of the bounding box, normalized by the width and height of the image.
A list of 2D points that are connected to form a polygon. This list is ordered such that,
is connected to
. The last point is also connected to the first point to close the polygon.
A length measurement is defined by two points, and the length measurement is the distance between the two points.
Corresponding to
point1, point2 these are points in physical space.Measurements can be made on oblique planes.
normal defines the normal unit vector to the slice on which this annotation was made. For annotations made on non-oblique planes, the normal will be [0,0,1].The value of the measurement in mm.
Angle measurement is defined by three points, where the vertex is the middle point. The angle between the two vectors (vertex -> point1 and vertex -> point2) defines the angle measurement. These points are all represented in IJK image coordinate space.
Corresponding to
point1, point2, vertex, these values are coordinates in the DICOM world coordinate system i.e. physical space. Measurements can be made on oblique planes.
normal defines the normal unit vector to the slice on which this annotation was made. For annotations made on non-oblique planes, the normal will be [0,0,1].The value of the angle in degrees.
When exporting consensus annotations, the Tasks JSON file and the
segmentations/ directory will have a slightly modified structure. Each task folder will contain all the users' segmentation files. The segmentation files can be uniquely identified by the index "_1" at the end of the file. You will be able to map between the users email and the index in tasks.json.
project_id/
├── segmentations
│ ├── study01
│ │ ├── series1_1.nii
│ │ └── series1_2.nii
│ └── study02
│ ├── series1_1.nii
│ └── series1_2.nii
└── tasks.json
// Single task on RedBrick can be single/multi-series
type Task = {
// Required on upload and export
name: string;
consensus: true;
consensusScore: number; // overall consensus score
consensusTasks: ConsensusTask[]
// Only required on export
taskId?: string;
currentStageName?: string;
createdBy?: string;
createdAt?: string;
updatedBy?: string;
updatedAt?: string;
};
type ConsensusTask = {
updatedBy: string;
updatedAt: string;
scores: {secondaryUserEmail: string, score: number}[]
series: Series[]
}
The consensus task object contains information about the consensus annotations for this task.
There will be a single entry for every annotator who annotated this task. For example, if 3 users annotated each task in your project, the length of the consensusTasks array will be 3.The e-mail of the user who annotated the task.
The datetime when the user last updated the task.
The
scores entry compares the current users' annotations with every other user. The scores array will be of length n-1, where n is the number of users who annotated this task. score is the similarity score between the current user, and secondaryUserEmail.Last modified 4d ago