Tag Points

Tag points are sets of three dimensional points which are used to mark positions of interest. Generally these result from manually locating corresponding positions in multiple volumes to provide a mapping among the volumes. Tag points are stored in an ascii format devised at the McConnell Brain Imaging Centre, with a convention of filenames ending in .tag. A tag file can contain either sets of single tag points or two tag points, depending on whether the file corresponds to one or two volumes. Each tag point consists of three coordinates, x, y, and z. Each set of one or two tag points has additional optional information stored with it. A tag point set may or may not include a set of three values: a real valued weight, an integer structure id, and an integer patient id. A tag point may or may not include a label string. Functions to read and write files of this format are described:

public  Status  input_tag_points(
    FILE      *file,
    int       *n_volumes,
    int       *n_tag_points,
    Real      ***tags_volume1,
    Real      ***tags_volume2,
    Real      **weights,
    int       **structure_ids,
    int       **patient_ids,
    char      ***labels )
public  Status  input_tag_file(
    char      filename[],
    int       *n_volumes,
    int       *n_tag_points,
    Real      ***tags_volume1,
    Real      ***tags_volume2,
    Real      **weights,
    int       **structure_ids,
    int       **patient_ids,
    char      ***labels )

These two functions read a set of tag points from a file. The first form assumes the file is already open and will be closed by the calling function, while the second form opens and closes the file specified by a filename, with a default extension of .tag. The number of volumes (number of tags in a set, currently either one or two) is passed back in the n_volumes argument. The number of tag points is passed back in the n_tag_points argument. The three dimensional coordinates of the first tag point in each set is passed back in the argument tags_volume1. If the number of volumes is two, then the second tag point in each set is passed back in the argument tags_volume2. The final four arguments pass back the auxiliary information associated with each tag point set. If the calling program is not interested in any one of the four data, then it can pass in a NULL pointer and the values in the file will not be passed back.

public  void  free_tag_points(
    int       n_volumes,
    int       n_tag_points,
    Real      **tags_volume1,
    Real      **tags_volume2,
    Real      weights[],
    int       structure_ids[],
    int       patient_ids[],
    char      **labels )

When finished with a list of tag points, the associated memory may be freed by calling this function.

public  Status  output_tag_points(
    FILE      *file,
    char      comments[],
    int       n_volumes,
    int       n_tag_points,
    Real      **tags_volume1,
    Real      **tags_volume2,
    Real      weights[],
    int       structure_ids[],
    int       patient_ids[],
    char      **labels )
public  Status  output_tag_file(
    char      filename[],
    char      comments[],
    int       n_volumes,
    int       n_tag_points,
    Real      **tags_volume1,
    Real      **tags_volume2,
    Real      weights[],
    int       structure_ids[],
    int       patient_ids[],
    char      **labels )

These two functions write a list of tag points to a tag point file. The first form assumes that the file has already been opened and will be closed later by the calling function, while the second form opens and closes the file, with the default extension of .tag. The comments argument is any arbitrary string documenting the contents of this file. The number of volumes (n_volumes) must be either one or two. The number of tag points is specified by the argument n_tag_points. The positions of the sets of one or two tag points are in the arguments tags_volume1 and tags_volume2. If any of the three arguments, weights, structure_ids, or patient_ids, are specified as NULL, then none of these three pieces or information is written to the file. Similarly, if the labels argument is NULL, then no labels are written to the file.

• Source Code Example