File format

For now, ROIs and Groups are saved in a regular text-based CSV format.
Hopefully, it is organized in a self-explanatory manner.
Not sure if it is the best way. As the plugin develops, maybe it will change.
We are willing (and planning) to write an "ROIs reader" function for Matlab/Python, if there would be a request.

The most important is that coordinates of points and lines are stored in "pixel/voxel" units, not in scaled units (micrometers, etc). So you need to know voxel characteristics of original dataset to convert it to "true" measurements.

Here is a typical structure of ROI file. It starts with a block about Groups:

BigTrace_groups	version	0.0.4		
GroupsNumber	2			
BT_Group	1			
Name	*undefined*
....  groups parameters ....						
End of BigTrace Groups				

Followed by ROIs information:

BigTrace_ROIs	version	0.0.5
ImageUnits	micron
ImageVoxelWidth  0.1326897526490514
ImageVoxelHeight 0.1326897526490514
ImageVoxelDepth  0.3530060569122018
ROIsNumber	3	
BT_Roi	1	
....ROI parameters ....
BT_Roi	2
....ROI parameters ....
End of BigTrace ROIs

The header contains voxel's scale information and its units. Upon loading ROI file it will be applied to the current dataset (see View/Crop panel).

Each ROI description starts with information about its appearance and type:

Type	Point               // (or Polyline or LineTrace)		
Name	polyl1479209238			
GroupInd	0 	    // (Group index starting from 0)		
PointSize	6	    // (in voxel units)
PointColor	0	255	0	255 // (alpha, RGB format 0-255)
LineThickness	4          // (in voxel units)	
LineColor	0	0	255	255 // (alpha, RGB format 0-255)
RenderType	1	       // (0 - center line, 1 - grid, 2 - surface)		
SectorN	16

For Point and Polyline ROIs following field is Vertices with a number of vertices (always 1 for Point). Example:

Vertices	5		
314	346	191	0
309	307	136	0
302	269	118	0
297	233	103	0
296	208	92	0

Here in case of Polyline we have 5 points, so there are five subsequent lines
with X, Y, Z and T coordinates (T for now is always 0, since timelapse is not supported). Vertices are ordered by the time of addition.

The LineTrace ROIs description also starts with list of vertices (points clicked by user, same XYZT format). Again, they are ordered by addition:

Vertices	5		
163	227	140	0
182	179	122	0
199	98	78	0
204	59	65	0
216	15	45	0

After that section, it has coordinates of segments connecting these vertices. I.e. segment 1 connects vertices 1 and 2, segment 2 -> vertices 2 and 3, etc.

These segments are made from a different number of points themself, specified in the Points field. In this example above, there are 5 points, so there should be 4 connecting segments:

SegmentsNumber	4		
Segment	1	Points	49
163	227	140	0
164	226	141	0
...
181	180	122	0
182	179	122	0
Segment	2	Points	82
182	179	122	0
182	178	122	0
...
199	99	78	0
199	98	78	0
Segment	3	Points	40
...
Segment	4	Points	45
....

Notice, that each segment includes two Vertices points' coordinates as its start and end. Therefore first point of Segment 2 is the last point of Segment 1 and the second value in the Vertices list.

Hopefully, this description is clear. If you have questions, send me an email.