The btf File Format
Contents
Introduction
The btf file format evolved because the BORG Lab needed a way of storing
important information from a video file. This includes information such as size, position, and characteristics of objects inside the
video files. The btf format was designed to allow it to be easily parsed, and expandable by end users.
Return to Top
Folder Format
If you recieve a btf file, you really are recieving a folder full of plain text files that end in .btf. Each of these files represent some
characteristic that is observed.
It is typical for a btf folder to have a name that ends in .btf.
Return to Top
File Format
Inside a btf folder, you will find a series of files that end with .btf. The name of these files represents a characteristic that that file tracks.
For instance, if you were to open a file called xposition.btf you would fine that the data inside of this file represents the X position of an object.
How is the data stored inside these files?
Each file is a plain text, newline separated file. There is one data field per line.
|
Important Convention
|
|
In order for a btf file to "make sense", it is important that the data in the files correlate "linearly", that is, line 1 in every file
should reference object A, line two in every file should reference object B, etc.
|
So, when reading multiple btf characteristic files, it is important to keep all the file pointers pointed to the same line across all the files you have
open.
Return to Top
Typical Files
The following is a list of some files that you might find in a btf folder, and what characteristic that file represents.
|
File Name (Ends in .btf)
|
Data Type
|
What do the contents represent
|
| README | ASCII text | Contains various text information regarding history, etc. Meant for information to humans, and not meant
or intended to be a program readable format. NOTE: README is the only file that does not end in .btf |
| General Information |
| timestamp | long | Timestamp in milliseconds since 1970 |
| mark | int | The manner in which the object is marked. Often used to represent colors |
| ximage | double | X location in image space (pixels) |
| yimage | double | Y location in image space (pixels) |
| zimage | double | Z location in image space (pixels) |
| xblobsize | double | 1/2 of the width of the blob (pixels) |
| yblobsize | double | 1/2 of the height of hte blob (pixels) |
| timage | double | orientation of the object (radians) |
| orientation | double | angle of the object, (radians). 0 to 2PI, 0 indicating +X direction |
| Identification |
| id | int | the ID of the object |
| Real World Scaling |
| xscale | double | X location in real space (meters) |
| yscale | double | Y location in real space (meters) |
| zscale | double | Z location in real space (meters) |
| tscale | double | Orientation of the object (radians) |
| Used for some bee analysis programs |
| display_type | int | which color to use when displaying the track. Commonly 0=black, 1=red, 2=green, 3=blue. |
| label0 | ASCII | A text label |
| label1 | ASCII | A text label |
| v0 | double | single-step velocity |
| v1 | double | velocity averaged over a window |
| h0 | double | single-step heading |
| h1 | double | single-step heading change |
| h2 | double | "curvature" over a large window |
| sh0 | double | v0 * h1 |
| sh1 | double | sh0 averaged over a window |
| Used for some ant analysis programs |
| i_headtohead | int | id of interacting ant, 0 otherwise |
| i_headtobody | int | id of interacting ant, 0 otherwise |
| i_bodytobody | int | id of interacting ant, 0 otherwise |
| i_bodytohead | int | id of interacting ant, 0 otherwise |
Return to Top
Example btf file
The following is an example of what you might find in a btf folder.
| Directory Contents |
|---|
README
ximage.btf
yimage.btf
xblobsize.btf
yblobsize.btf
framestamp.btf
id.btf
|
|
| README |
|---|
Generated by Ron Researcher on 10/13/03.
Avi was captured by using a Canon 304 DV camera.
File describes the motion of three bees in a fishbowl.
|
|
| Contents of ximage.btf |
|---|
56
58
60
70
80
90
...
|
|
| Contents of yimage.btf |
|---|
14
93
67
10
74
54
...
|
|
| Contents of xblobsize.btf |
|---|
45
34
20
34
45
20
...
|
|
| Contents of yblobsize.btf |
|---|
23
45
78
78
44
23
...
|
|
| Contents of framestamp.btf |
|---|
0
0
0
1
1
1
...
|
|
| Contents of id.btf |
|---|
1
2
3
3
1
2
...
|
|
As you can see from this example file, there is no gaurenteed order to the btf files. The only gaurantee is that
everything on the same line number will belong to the same object. In this case, the third line of the file would
say that object 3 has a center of (60,67) and a size of (20*2, 78*2), and then only during frame 0. In this case,
the next frame, object 3 is on line 4, instead of line 6 as would be expected from a logical ordering. The object itself
changes to a center of (70,10) and a size of (34*2,78*2).
The one safe thing to assume is that there will generally only be one of any given object per frame.
Return to Top
|
