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 most optimal 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.

Most importantly, the coordinates of points and lines are stored in "pixel/voxel" units, not in scaled units (micrometers, etc). So you need to know the voxel characteristics of the 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.3.0		
GroupsNumber	2			
BT_Group	1			
Name	*undefined*
....  groups parameters ....						
End of BigTrace Groups				

Followed by a header and ROIs information:

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

The header contains voxel's/time scale information and corresponding units.

Upon loading the ROIs file it will be applied to the current dataset (see Panel View Crop) panel).

Each ROI record starts with a header information about its appearance, type, and corresponding time point:

Type	Point               // (or Polyline or LineTrace)		
Name	polyl1479209238			
GroupInd	0 	    // (Group index starting from 0)
TimePoint	0 	    // (notice that the time frame index starts 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)		

For Point and Polyline ROIs the next record is Vertices with a number of vertices (always equal to 1 for Point3D type ROI). Example:

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

Here in the case of Polyline we have 5 points, so there are five subsequent lines
with X, Y, Z coordinates. The last added point would be the last in the list.

The LineTrace ROIs description also starts with a list of vertices (3D points selected by the user, in the same XYZ format):

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

In addition, it has a record of traced curve 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
164	226	141
...
181	180	122
182	179	122
Segment	2	Points	82
182	179	122
182	178	122
...
199	99	78
199	98	78
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.

I hope this description is clear for you. If you have questions, send me an email.