VisionX V4

vlmap − manage regions in a label map


vlmap [-H] [if=<inputfile>] [ig=<inputfile>] [of=<outputprefix>] [o=] [-i] [-a] [-b] [-e] [-d] [-g] [-wd] [-wg] [-c] [-l] [-t] [-v] [o1=] [o2=] ... [o15=] [p=]


Vlmap is used to manage a label map. A label map is a VisionX image in which the pixels represent region labels. For chest CT image analysis there is a predefined set of primary labels that relate to anatomical regions such as lungs, ribs, etc. A label map pixel can only take the value of one primary label at a time. There is also the concept of label groups. For example, group lungs includes the labels lung, left-lung, and right-lung. Only primary labels may be written to the map while groups of labels (by group names) or explicit lists of label names may be read from a map. A list of the currently defined primary labels, and the group labels with their members may be obtained by executing vlmap with the -l option.

The main operations defined for label maps are creation (-i), deletion of a label (-d) addition of a label or labels (-a) and extraction of a label or labels (-e). In addition the existence of a label may be tested (-c). There is a color associated with each label. A color image may be generated for a map with the -t option.

A set of labels may be preserved by the p= parameter. That is when the -a or -b option is selected, labels in the p= list cannot be overwritten with new data.

Single Label Management

A single label may be added to the label map with the -a option and the label name specified by the o= option. A binary mask (ig=) with values 0 and non-zero specifies the region associated with the label. Only primary labels may be added. The new label will overwrite any other labels already specified for pixels where it is set. To extract a single label use the -e option and the label specified by o= option will be output as a binary mask with values 0 and 255. In this case, a group label name will select all existing labels for that group.

Multiple Label Management.

For multiple label operations, binary masks are replaced by numeric images in which labels are represented by small integer values. The mapping of these values to labels is realized by the parameters o1= ... on=.

A set of labels in a single image may be written to a map if o1= ... on= parameters are specified with -a instead of o=. The label specified by o1= will be set by all pixels in the ig= file that have the value 1 and the label specified by o2= will be set by all pixels that have the value 2 etc. With this scheme currently up to 15 primary labels may be added to a map with a single command execution.

A set of labels for extraction may also be specified by the o1= to on= parameters with the -e option. In this case a numeric output image is generated in which the value <i> corresponds to the labels specified for parameter o<i>=.

When an extraction (-e) operation is performed using either the o= or o<i>= parameters the parameter argument may be a list of labels (including group labels). In such cases all labels in the list are mapped to the corresponding output value.

There is a hierarchy of labels achieved by using group labels, such that specifying one label will also include all its subcomponents. For example, the lung may consist of both the left and right lungs. Run vlmap with -l to see all known label types.

The program may be run with -b flag to merge multiple label maps. In this case any labels in the ig= file will overwrite any corresponding labels in the if= file.

To create a color map of organs in a label map, -t flag is used. When -t flag is used, ig= should be a VTK color configuration file (.vkc). Refer to v3view’s man page for details on the color file.



Input Image map


Input Image2: binary segmented organ (-a and o=) image with desired structure (-i option) or numeric image (options o1= ... on=) or lut file (-t).


Output File: new label map if adding, new binary or numeric image if extracting, and color image for -t.


label or list of labels to extract/add (use -l flag to see listing)

o1=, o2= ...

Specifies a label or list of labels to be associated with a numeric value.


Specifies a label or list of labels that are to be preserved. That is they pixels with these labels will not be overwritten when -a or -b is specified.


Add a label mask i or a set of values (o1= , o2= ...) to the map. When a set of values is specified, values in the ig= file with no corresponding o<n>= specification will be ignored.


Write any non-zero pixel in ig= to the map


Extract an organ mask from the map


Permanently delete an organ from the map as specified by o=<list>


Permanently delete an organ from the map as specified by o=<list> (group names take precedence over primary label names)


Print in wish format the comparison between two maps for the given labels (o=<list>) the values returned are: n1, number of matching labels found in image 1 (if=); n2, number of matching labels found in image 2 (ig=); nsame, number of matching labels found in same locations (both images); nexact, number of matching labels found in same locations with exact same values (both images); dc, Dice coefficient for nsame; dce, Dice coefficient for nexact.


Simlar to -wd except that group names are considered in the o=<list>.


Initialize a map according to the size of the ig= file


Check to see if an organ exists in the map (group names take precedence over primary names)


List all known organ types in their hierarchy


Output true color organ map (the ig= parameter has the lut name)


Verbose mode



Only handles byte images


vlan(1), vslung(1)


A. P. Reeves, Jaesung Lee, Benjamin Stein