CSO Overview¶
Introduction¶
The acronym CSO stands for Contour Segmentation Objects.
The CSO library provides data structures and modules for interactive or automatic generation of contours in voxel images. Furthermore, these contours can be analyzed, maintained, grouped, and converted into a voxel image or a set of markers.
In the CSO library, all objects’ coordinates are stored in world space. The contours themselves are organized in a CSOList and are called CSOs. The CSOs are 3D objects and are not attached to any specific image. Because of this, they can be freely interchanged between different images or the same image with different resolutions. Also, due to their 3D nature, the CSOs are not restricted to the axial plane or any ortho-plane in general but can be generated on oblique MPRs. In one CSOList, arbitrarily and differently oriented CSOs can coexist.
Also part of a CSOList is a number of CSOGroups. There is no limit to the number of CSOs in a CSOGroup, and one CSO can be associated with multiple CSOGroups. These CSOGroups can be used to organize the CSOs, for example, grouping by structures that the CSOs describe in an image, and to change parameters of member CSOs by overwriting them with group parameters.
The CSOList can be saved to disk and loaded from there again. The file format can either be plain ASCII and human-readable or a fast binary format.
CSOList, CSO, and CSOGroup¶
The central object in the CSO library is the CSOList. It consists of a number of CSOs, which are the contours themselves. Additionally, a CSOList can contain a number of CSOGroups. A CSOGroup can contain any number of CSOs, and CSOs can be in any number of CSOGroups.
The CSO, as well as the CSOGroup, has an Attribute container as a member; thus, the CSOs and the CSOGroups share a set of attributes. These common attributes mostly concern visual matters, such as color, line width, or seed point size. The attribute parameters of a CSOGroup can be used to overwrite the corresponding parameters of its contained CSOs. Since a CSO can be a member of multiple CSOGroups, the first CSOGroup that overwrites a parameter is the one that actually does so. Besides the common attributes, the CSOs and CSOGroups yield specific attributes: the CSOs have a closed and an in-plane state, while the CSOGroups have rules for handling overflows as attributes. See below for more details.
A CSO can also store and persist an arbitrary number of user data entries with an arbitrary data type. Some modules generate user data, such as the SoCSOImageStatistics module; otherwise, the user data can be read and set via the CSO’s Python interface.
A user data entry consists of a name (string type) and a value (inferred data type).
Seed Points and Path Points¶
A CSO consists of a number of seed points and a number of path point lists. The path point lists, in turn, consist of a number of coordinates. Generally, the seed points are generated interactively and can be edited (moved, removed, or inserted), while the coordinates of the path points are computed by an interpolation scheme.
The seed points and the path point lists of a CSO are linked to each other. Each CSO is directed concerning its normal in a clockwise manner. This means that a path point list can be thought of as an edge in a graph, while the seed points can be considered nodes in a graph. In this context, each edge is directed and thus yields a head node and a tail node, while a node yields a preceding edge and a succeeding edge. In the actual implementation, these links are indeed established by pointers. If a CSO is not closed, the first and last seed points hold NULL pointers.
The seed points are mostly placed interactively (using an Editor module), while the path points result from an interpolation of these seed points.
All coordinates of seed points and path points are in world coordinates.
Notifications¶
In MeVisLab, the CSO library is implemented using separate modules that can interact to form a network.
Because the base data structure CSOList is derived from Base, the modules interchange only a pointer to a single CSOList. To synchronize multiple drawing or information modules, the library implements a notification-based event scheme. Each CSO module in a network registers itself in the CSOList if it is attached to any, with a callback routine that is invoked on certain events, such as finishing a CSO interaction, starting to generate a new CSO, or selecting other CSOs. The modules’ callback methods filter these notifications and react only to those they are implemented for. For fine-tuning the notification network, most CSO modules offer Listen to options. Through these flags, the reaction to special notifications can be turned on or off. Note that a module can only react to a notification if its update mode is set to Auto Update.
The CSOManager module offers the ability to explicitly trigger certain notifications, as well as fields for observing all notifications. The latter can be used as an interface to scripting. FieldListeners can be attached to these fields and trigger a scripting function upon receiving certain notification events.
The following types of notifications exist:
| Notification Type | Description |
|---|---|
| Finished | Is triggered when an interaction is finished, such as completing the rendering of a CSO, moving a seed point, removing a seed point or an entire CSO, or loading or filtering a CSOList. |
| Selection (Changed) | Is triggered when a new CSO is selected or added to an existing selection, as well as when a CSOGroup is selected. This notification is also triggered when any item is deselected. |
| Repaint | Is triggered when any visualization parameter has been changed. This notification is typically triggered in the same situations as the Finished and Selection notifications. |
| Interaction Init | Is triggered when a seed point, CSO, or CSOGroup has been removed to reset all interactive modules. |
| Start New CSO | Is triggered when the interactive generation of a CSO has been started. |
Note that the CSOFilter module may react to a Selection notification (or another notification) and subsequently copies and filters the input CSOList. After doing so, it triggers a Finished notification on the output CSOList.
Editors and Generators¶
The editor and generator modules are used to create new CSOs. Editors provide a specific type of interaction to produce and edit seed points while simultaneously offering a particular interpolation scheme to generate the path points. The SoView2DCSOExtensibleEditor enables the use of any editor extension and offers, in addition to drawing the CSOs, only basic interaction possibilities, such as selecting and moving arbitrary types of CSOs.
If an editor extension module is attached to the extensible editor and an existing CSO is selected for editing, the editing is performed only if the selected CSO is of the same type as the editor. The type and subtype of a CSO are displayed on the panel of the CSOInfo module. If the CSO is of a different type, the editor automatically switches to move mode. However, when a CSO is selected, the Selection notification is first triggered, causing attached modules like CSOInfo to immediately update their fields. The CSOInfo, for example, now shows the currently selected CSO’s type.
Generators generate CSOs, set seed points using an algorithm, and interpolate the path points afterward. They do not provide any capability for interactive editing.
Special Attributes¶
The process of converting a CSO to an ML image is referred to as voxelizing or rasterizing. For this purpose, two modules are available: CSOVoxelizeContours and CSOGenerateSmoothSurfaceFromSparseContours. The first module converts the path points into a connected list of voxels with optional filling, while the latter constructs a smoothed spline surface through all CSOs, resulting in an interpolated mask image. For both modules, the target voxel values must be determined. Each CSO (and CSOGroup) has a voxel write mode and a voxel write value. The voxel write mode determines how and where the target voxel value is set; this can either be done in the corresponding conversion module or stored by the CSO (or CSOGroup) itself. The voxel write value can be a constant (the voxel write value), the CSO’s ID, or the sum of the constant and the CSO’s ID.
Although a CSOGroup can potentially contain an unlimited number of CSOs, it may be necessary in applications to limit the number of CSOs for a particular CSOGroup. In this case, each group has an attribute rule called Maximum CSOs and an Overflow Handling option. If the value of the Maximum CSOs rule is 0, no limit is applied; if the value is greater than 0, it determines the maximum number of CSOs that this CSOGroup can contain. When the maximum number is reached and another CSO is about to be added, the Overflow Handling rule applies. Four actions can be chosen: Delete First, Delete Last, Delete All, and Ignore New.
The first three cases delete some or all of the existing CSOs in the respective CSOGroup, while the last case omits a new CSO from being drawn. Note that these rules apply only in conjunction with generating new CSOs by editors or generators, not when administering CSOs and CSOGroups using the CSOManager.