Annotation Files

Although Knossos can still load and export *.nml files, the recommended way is to use the new annotation files.

The annotation files *.k.zip are zip archives that can currently contain 4 things:

• A file annotation.xml which is formerly known as *.nml containing general information about the whole annotation and optionally a skeleton (for an easy start the contents are currently the same as you’d get when exporting as *.nml, but the vision is to split the skeleton from skeleton independent information in the future)
• several *.seg.sz files containing segmentation overlay cubes which are loaded at higher priority than files from disk and saved when cubes got edited
  the filenames consist of: the experiment name, '_', the magnification, 'x' 'y' and 'z' with their respective cubes coordinates
  e.g. 2012-03-07_AreaX14_mag1 _ mag1 x41 y40 z22 .seg.sz
  You can generate these by dumping the in-memory representation of a snappy-compressed cube into a file using a snappy library binding or a tool like snzip which does so with its snappy-in-java format.
• A file mergelist.txt containing information about objects which span multiple overlay ids with the format specified below
• Several *.ply files containing vertices, colors and indices to define a triangle mesh. The filename usually consists only of the tree id to which the mesh belongs. Otherwise the mesh will be associated to a newly created tree. Details about the format are specified below.

###Merge list

The merge list is used to group supervoxels (groups of voxels with the same unique ID) into objects and assign information to them. It’s just a text file where each object occupies 4 lines.

Object = Object_ID, ToDo_flag, Immutability_flag, Supervoxel_IDs, '\n', Position, [' ', Color], '\n', Category, '\n', Comment, '\n';

Object_ID = uint64, ' ';
ToDo_flag = Immutability_flag = (0|1), ' ';
Supervoxel_IDs = uint64, {' ', uint64};
Position = int32, ' ', int32, ' ', int32;
Color = uint8, ' ', uint8, ' ', uint8;
Category = Comment = −'\n';

Object_ID is a unique identifier for the group of Supervoxel_IDs.
ToDo_flag represents objects marked to be evaluated by the annotator.
The Immutability_flag is used to represent if an object should persist in the list after it was merged by proofreaders (i. e. for later unmerging, usually all initial objects given to proofreaders are marked as immutable).
Position are space-separated x, y and z voxel coordinates assigned to an object.
Color is an optional space separated tuple of the red, green and blue components of a custom color.
Category and Comment each occupy a line on their own – without any escape characters.

Example:

3150 1 1 5352 3297 3971 4104 2654 4153 4046 2257 3624 3150 4100
5333 5267 2880
mito
whatever one may want to add here

3151 1 0 2257 2654 2663 3018 3023 3029 3150 3294 3297 3298 3363
1024 2048 4096 16 25 222
neuron
proofread merge

Triangle Mesh (.ply)

A triangle mesh is a collection of vertices, colors and indices. The filename usually consists only of the tree id to which the mesh belongs. Otherwise it will be associated to a newly created tree. We use the ply file format for loading and saving meshes. We chose this format because it is very simple and extensible at the same time, it can be stored as text as well as binary and python and C++ libraries are available to create and read ply files. At the moment KNOSSOS can load ply files with following header:

ply
format: [ascii|binary_little_endian|binary_big_endian] 1.0
element vertex #vertices
property float x
property float y
property float z
element color #colors
property float r
property float g
property float b
property float a
element face #faces
property uint v1
property uint v2
property uint v3
end_header

The color element is optional. If no colors are specified, the mesh will have the same color as its skeleton tree. Example:

ply
format: ascii 1.0
element vertex 3
property float x
property float y
property float z
element color 3
property float r
property float g
property float b
property float a
element face 1
property uint v1
property uint v2
property uint v3
0 0 0
100 0 0
50 50 0
1 0 0 1
1 0 0 1
1 0 0 1
1 2 3