CSO Overview

Introduction

The acronym CSO stands for Contour Segmentation Objects.

The CSO library provides data structures and modules for an 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 CSO. The CSOs are 3D objects and are not attached to any specific image. Because of that, they can freely be 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 to any ortho-plane in general, but can be generated on oblique MPRs. Of course, 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 group 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 hard disc 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. Also, 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, so, the CSOs and the CSOGroups share a set of attributes. These common attributes concern mostly which visual matters, like a color, a line width, or a seed point size. The attribute parameters of a CSOGroup can be used to overwrite the according parameters of its contained CSOs. Since a CSO can be a member of multiple CSOGroups, the first of the CSO’s group that is overwriting some parameter is actually overwriting it. Besides the common attributes, the CSOs and the CSOGroups yield specific attributes, like 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 with an arbitrary data type. Some modules generate user data, e.g., 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 (type string) 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 list. The path point lists again 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, in respect to 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 thought of as 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 the last seed points hold NULL pointers.

The seed points are mostly placed interactively (by using an Editor) 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 realized using separate modules that can interact in order to form a network.

Because the base data structure CSOList is derived from Base, the modules interchange only a pointer to one CSOList. For synchronizing possible 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 called on certain events, like finishing a CSO interaction, starting to generate a new CSO or selecting some other CSOs. The modules’ callback methods filter these notifications and react only on those they are implemented for. For fine tuning the notification network, the most of the CSO modules offer some Listen to options. By these flags, the reaction to special notifications can be turned on or off. Note that a module can only react on a notification if its update mode is set to Auto Update.

The CSOManager module offers the possibility to explicitly trigger some of the notifications, as well as fields for observing all notifications. The latter can be used as an interface to scripting. FieldListeners can be attached to those fields and trigger some scripting function on receiving certain notification events.

The following types of notifications exist:

Finished	Is triggered if an interaction is finished, like finishing to draw a CSO, finishing to move a seed point, after the removal of a seed point or a whole CSO, or after loading or filtering a CSOList.
Selection (Changed)	Is triggered if a new CSO is selected, or added to an existing selection, as well as a CSOGroup is selected. Of course, this notification is also triggered if any item has been deselected.
Repaint	Is triggered if any visualization parameter has been changed. This notification is mostly triggered in the same situations the Finished and Selection notifications are triggered.
Interaction Init	Is triggered if a seed point, a CSO or a CSOGroup has been removed in order to reset all interactive modules.
Start New CSO	Is triggered if the interactive generation of a CSO has been started.

Note that the CSOFilter module may react on a Selection notification (or some other), and then copies and filters the input CSOList. After doing so, it triggers a Finished notification on the output CSOList.

Editors and Generators

The editor and the generator modules are used to create new CSOs. Editors offer a certain type of interaction to produce and edit seed points and offer at the same time a certain type of an interpolation scheme to generate the path points. The SoView2DCSOExtensibleEditor enables the use of any editor extension and offers, besides the drawing of the CSOs, only basic interaction possibilities like selecting and moving of arbitrary types of CSOs

If there is an editor extension module attached to the extensible editor, and an existing CSO is selected for editing, the editing is only performed if the selected CSO is of the same type as the editor. The type and subtype of a CSO is displayed on the panel of the CSOInfo module. If the CSO is of a different type, the editor automatically switches to move mode. However, on selecting a CSO, at first the Selection notification is triggered and thus, attached modules like the CSOInfo immediately updates their fields. Now, the CSOInfo for example shows the currently selected CSO’s type.

Generators just generate CSOs and set seed points by some algorithm and interpolate the path points afterwards. They do not offer any possibility for an interactive editing.

Special Attributes

The converting of a CSO to an ML image is called voxelizing or rasterizing. For this purpose, there are two modules available: CSOVoxelizeContours and CSOGenerateSmoothSurfaceFromSparseContours. The first one converts the path points into a connected list of voxels with an optional filling, and the latter one constructs a smoothed spline surface through all CSOs, resulting in an interpolated mask image. For both modules, the target voxel values must be determined. For this purpose, 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 that the value is set in the according conversion module, or that the CSO (or the CSOGroup) stores itself the value. Then, this value can be a constant (the voxel write value), the CS’s id, or the sum of the constant and the CSO’s id.

Although a CSOGroup can potentially contain an unlimited amount of CSOs, it can be necessary in applications to limit the amount of CSOs for a certain CSOGroup. For this case, each group has an attribute rule Maximum CSOs and an Overflow Handling. If the value of the first one is 0, no rule is applied, if the value is greater than 0, this value determines the maximum amount of CSOs this CSOGroup can contain. If the maximum number is reached and another CSO is about to be added, the Overflow Handling rule applies. Out of 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 of the concerning CSOGroup while the last case omits a new CSO being drawn. Note that these rules only apply in conjunction with generating new CSOs by editors or generators, not with administering CSOs and CSOGroups with the CSOManager.