Purpose

The module CSOVoxelizeContours converts all CSOs of the input CSOList to an ML image.

It rasterizes or voxelizes the CSOs with the according voxelize flag set to ‘true’ into the output image. If a CSO is in-plane, it also can be filled.

Usage

Attach a CSOList and an ML image to the module’s inputs, adjust the parameters and press Update.

Details

General

The contour itself is converted into a 6-connected line of voxels. This is computed by following a contour’s segments through the voxels by applying a derivate of a marching cubes scheme. In this scheme, the cells are checked for which cell’s side the contour segments are crossing.

A filling of the voxelized contours is computed by applying a marching cube algorithm where the CSO’s plane equation is evaluated (it can be evaluated to ‘is above-’, ‘is below-’ and ‘is on plane’, resulting in a scalar). Additionally, all cells’ middle points in the vicinity of the voxelized CSO are projected onto the CSO’s plane and are checked for being inside the CSO. If a certain amount of cells are determined in this fashion, a sufficiently ‘thick’ security margin is computed, so that all the remaining cells can be computed by applying a recursive marching cube algorithm that test only against the plane equation.

The set voxels of the rasterized CSO itself and the set of voxels of the according filling are disjunctive.

Boolean Operations

If CSOs are crossing each other or are embracing each other, they will generate voxels at same positions. In such cases, the resulting ML image value can be determined by using a certain logic mode. This can be an adding of those voxel values, a replacing with the greater or lower voxel value, or an applying of an XOR operation. The result of the latter depends on the order of computing and may lead to different results if the CSOs’ voxel write mode involves either their ids or different constants. If the voxel write mode of all CSOs is set to Module (the default), however, the XOR operation can safely be used for generating holes in contours by using other contours. If the voxel write mode is different and different voxel write values are used, such holes are produced as well, but if there is an odd number of CSOs (more than 1), the resulting voxel value cannot be predicted for sure.

Time Points

The input CSOs may have different time point indices. For voxelizing CSOs to the correct time point index, the input image must have the correct amount of time points.

The voxel bounding box can be computed for a certain time point or for all time points combined. There is the field Time Point Index (-1: all) to control this.

The module must be in Generation Mode Complete to correctly compute the voxel bounding box.

Miscellaneous

Note that the border voxels can be generated with anti-aliased values, but the border voxels of those holes will not be anti-aliased.

The module can either convert all incoming CSOs at once on each notification, or just those which cross any demanded image page. Note that the voxel count, the generation of markers, and the voxel bounding box fields are only valid if the generation mode is set to Complete.

The OnDemand mode is intended to be used in interactive systems.

Additionally, the module can output all target voxels as markers and as CSOVoxelSet. In both representations, the Boolean logic is not applied and thus, crossing or overlapping CSOs result in doubly existing markers or CSOVoxels.

Windows

Default Panel

../../../Modules/ML/MLCSOModules/mhelp/Images/Screenshots/CSOVoxelizeContours._default.png

Input Fields

input0

name: input0, type: Image

The reference input image. Values of the input image can also be copied to the module’s output.

inCSOList

name: inCSOList, type: CSOList(MLBase)

The input CSOList.

For accessing this object via scripting see the Scripting Reference: MLCSOListWrapper.

Output Fields

output0

name: output0, type: Image

The output image.

outputXMarkerList

name: outputXMarkerList, type: XMarkerList(MLBase)

Output marker list. The creation of markers is optional, see Create marker list.

For accessing this object via scripting see the Scripting Reference: MLXMarkerListWrapper.

outputVoxelSet

name: outputVoxelSet, type: CSOVoxelSetList(MLBase)

Output CSOVoxelSet. The creation of markers is optional, see Create CSO voxel set.

For accessing this object via scripting see the Scripting Reference: MLCSOVoxelSetListWrapper.

Parameter Fields

Visible Fields

Mode

name: updateMode, type: Enum, default: AutoClear

Defines how the module react on input changes. This includes touching, connecting and disconnecting of inputs as well as notifications of the CSOList (if enabled).

Values:

Title Name Description
Off Off The module does not react on input changes.
Auto Update AutoUpdate The module computes anew if any input changes or a valid notification is triggered.
Auto Clear AutoClear  

Auto apply

name: autoApply, type: Bool, default: FALSE

If checked, the module computes anew on any change of a field on the GUI.

Update

name: apply, type: Trigger

If pressed, the module computes anew.

Foreground

name: foregroundValue, type: Float, default: 4095

Sets the object voxel value if the CSO’s voxel write mode is set to Module (which is the default), and if the module is not using image values for the object voxels (Use image values).

Background

name: backgroundValue, type: Float, default: 0

Sets the background voxel value if the module is not copying the input image’s values (Use image values).

Use image values

name: useImageValues, type: Bool, default: FALSE

If checked, the input image’s voxel values are used as object voxel values.

Fill

name: fillSurface, type: Bool, default: TRUE

If checked, the CSOs which are in-plane are filled.

Copy input image

name: copyInputImage, type: Bool, default: FALSE

If checked, the background of the output image is filled with the voxel values of the input image.

Repaint

name: listenInteractionNotifications, type: Bool, default: FALSE

If checked, and the module’s Mode is set to Auto Update, each repaint notification of the CSOList leads to a new computation of the output.

Finishing

name: listenInteractionFinished, type: Bool, default: TRUE

If checked, and the module’s Mode is set to Auto Update, each interaction finished notification of the CSOList leads to a new computation of the output.

Margin

name: boundingBoxMargin, type: Integer, default: 0, minimum: 0

Sets an augmentation value for the voxel bounding box.

Start (startVoxelBoundingBox)

name: startVoxelBoundingBox, type: Vector3, persistent: no

Shows the upper front left corner position of the voxel bounding box.

End (endVoxelBoundingBox)

name: endVoxelBoundingBox, type: Vector3, persistent: no

Shows the lower rear right corner position of the voxel bounding box.

Start (startWorldBoundingBox)

name: startWorldBoundingBox, type: Vector3, persistent: no

Shows the upper front left corner of the bounding box in world coordinates.

End (endWorldBoundingBox)

name: endWorldBoundingBox, type: Vector3, persistent: no

Shows the lower rear right corner of the bounding box in world coordinates.

String

name: voxelBoundingBoxString, type: String, persistent: no

Shows the voxel bounding boxes start and end position as a string consisting of six 3D coordinates separated by a space.

Use Always Foreground Value Of Module

name: useAlwaysForegroundValueOfModule, type: Bool, default: FALSE

If checked, the voxel write mode of the CSO or CSOGroup are ignored and the foreground value of the module is used in any case.

Clear

name: clear, type: Trigger

If pressed, the output image of the module is cleared and invalidated.

Voxelize border

name: voxelizeCSO, type: Bool, default: FALSE

If checked, the path points of the CSOs themselves are voxelized into the output image.

Use global subsample

name: useGlobalSubsample, type: Bool, default: TRUE

If checked, the module uses the Subsample value for subsampling in order to determine border voxel values for useAntiAliasing or for removeBorderVoxelsByVolume.

Otherwise, the module uses the explicit subsample values for x, y and z directions (X, Y and Z).

Subsample

name: antiAliasSubSample, type: Integer, default: 4, minimum: 1, maximum: 6

Sets a global subsample value that is used if Use global subsample is checked.

X

name: antiAliasSubSampleX, type: Integer, default: 4, minimum: 1, maximum: 6

Sets the explicit subsample value in x-direction. Is used if Use global subsample is unchecked.

Y

name: antiAliasSubSampleY, type: Integer, default: 4, minimum: 1, maximum: 6

Sets the explicit subsample value in y-direction. Is used if Use global subsample is unchecked.

Z

name: antiAliasSubSampleZ, type: Integer, default: 4, minimum: 1, maximum: 6

Sets the explicit subsample value in z-direction. Is used if Use global subsample is unchecked.

Volume Threshold

name: removeBorderVoxelVolumeThreshold, type: Double, default: 0.6, minimum: 0, maximum: 1

Sets a threshold value for the border handling. If the border voxel is covered by a less percentage by the CSO, if can be removed from the resulting voxel set.

Ignore time points

name: ignoreTimePoints, type: Bool, default: FALSE

If checked, the timepoint indices of the input CSOs are ignored and the CSOs of all timepoint indices are voxelized into the first t-dimension of the output image.

Draw to all time points

name: drawToAllTimePoints, type: Bool, default: FALSE

If checked, all CSOs are voxelized into all t-dimensions of the output image.

Create marker list

name: createMarkerList, type: Bool, default: FALSE

If checked, a marker list output is filled with a marker per converted voxel of a CSO.

The value of a marker is the id of the originating CSO.

Marker Generation Mode

name: markerGenerationMode, type: Enum, default: CSOMarkerGenerationModeFromVoxels

Defines whether the markers are being generated before or after applying the Boolean logic to the resulting voxels.

Values:

Title Name Description
Voxels CSOMarkerGenerationModeFromVoxels Markers are being generated after the Boolean logic has been applied.
CSOs CSOMarkerGenerationModeFromCSOs

Markers are being generated before the Boolean logic has been applied.

That means that some markers may have the same position.

Output Type Mode

name: outputTypeMode, type: Enum, default: Automatic

Allows to specify which group of datatypes should be used for the output.

Values:

Title Name Description
Automatic Automatic The datatype is automatically calculated to fit the value that are written to it and to be able to contain the input image precision. Please note that the output will be float if the input image is float or if the range of the output image is smaller or equal to 1. If you always want an integer or unsigned integer output, switch to the according mode.
Unsigned Integer UnsignedInteger Use an unsigned integer type, regardless of the input image and the range. If any negative value is written to the output image, the output type will be switched to a signed integer type to hold the range correctly.
Integer Integer Use a signed integer type, regardless of the input image and the range.
Float Float Use the float datatype as output type (regardless of the input and the range of written values).

Voxel

name: voxelCount, type: Integer, persistent: no

Shows the amount of resulting voxels in the output image.

Create CSO voxel set

name: createCSOVoxelSet, type: Bool, default: FALSE, deprecated name: createCSOVoxelFormat

If checked, a CSOVoxelSet is created. This is a sparse representation of the resulting mask image.

Logic for Overlapping CSOs

name: voxelSetMode, type: Enum, default: VoxelSetModeReplaceMax

Defines how voxels of overlapping CSOs are handled.

Values:

Title Name Description
Add VoxelSetModeAdd Values of voxels at the same position are added.
Replace Max VoxelSetModeReplaceMax The maximum value of voxels at the same position is set.
Replace Min VoxelSetModeReplaceMin The minimum value of voxels at the same position is set.
XOR VoxelSetModeXOR

An XOR operation is applied to the voxel position. That means that the voxel is set if the number of resulting voxels for a position is uneven, and the voxel is unset (background) if the number is even.

By using this option, holes in contours can be modeled.

CAUTION: The XOR mode might lead to unexpected results. Please check section Boolean Operations above for details.

Generation Mode

name: generationMode, type: Enum, default: GenerationModeComplete

Defines the generation mode.

Values:

Title Name Description
Complete GenerationModeComplete On computing the result, all CSOs are being converted to voxels and the result is held in an internal structure for being copied to the output page if demanded.
On Demand GenerationModeOnDemand Only the CSOs are voxelized that are being cut by a requested output page and the result is written into an internal storage.

Use fast mode for parallel CSOs

name: useFastModeForParallelCSOs, type: Bool, default: TRUE

If checked, the CSOs that are parallel to the image’s main plane (e.g., parallel to the axial plane in an axial image) are filled with a much faster algorithm. However, because of the optimization, the resulting voxels may differ a bit from the result of the slower mode.

Num. Threads

name: numThreads, type: Integer, default: 1, minimum: 1

Sets the number of threads for parallel computation.

Time Point Index (-1: all)

name: timePointIndexForBoundingBox, type: Integer, default: -1, minimum: -1

Sets the time point index for voxel bounding box computation.

With time point index of -1, the voxel bounding box is comprised of all CSOs at all time points.

Remove Outside Voxels Mode

name: removeOutsideVoxelsMode, type: String, default: Disabled

Defines the border mode. Only available if Voxelize border is checked.

Possible values are:

Value Meaning
Disabled No border handling, all border voxels are written into the output image
Midpoint If the midpoint of a voxel lies within a CSO, it is written into the output image, otherwise it is skipped
Volume If the volume (projected area) of the portion of the voxel that lies within the CSO is greater than Volume Threshold, it is written into the output image, otherwise it is skipped
AntiAliasing The value of the output voxel is proportional to the projected area that lies within the CSO

Hidden Fields

isProcessing

name: isProcessing, type: Bool, persistent: no

done

name: done, type: Trigger, persistent: no

removeOutsideVoxels

name: removeOutsideVoxels, type: Bool, default: FALSE

Hidden field, is set by scripting. Do not change!

useAntiAliasing

name: useAntiAliasing, type: Bool, default: FALSE

Hidden field, is set by scripting. Do not change!

removeBorderVoxelsByVolume

name: removeBorderVoxelsByVolume, type: Bool, default: FALSE

progress

name: progress, type: Float, persistent: no