IDLgrVolume Properties

IDLgrVolume objects have the following properties in addition to properties inherited from any superclasses. Properties with the word “Yes” in the “Get” column of the property table can be retrieved via IDLgrVolume::GetProperty. Properties with the word “Yes” in the “Init” column of the property table can be set via IDLgrVolume::Init. Properties with the word “Yes” in the “Set” column in the property table can be set via IDLgrVolume::SetProperty.

Note: For a discussion of the property description tables shown below, see Modifying Object Property Descriptions.

Objects of this class have the following properties.

ALL

ALPHA_CHANNEL

AMBIENT

BOUNDS

CLIP_PLANES

COMPOSITE_FUNCTION

DATA0

DATA1

DATA2

DATA3

DEPTH_CUE

HIDE

HINTS

INTERPOLATE

LIGHTING_MODEL

OPACITY_TABLE0

OPACITY_TABLE1

PARENT

REGISTER_PROPERTIES

RENDER_STEP

RGB_TABLE0

RGB_TABLE1

SHADER

TWO_SIDED

VALID_DATA

VOLUME_SELECT

XCOORD_CONV

XRANGE

YCOORD_CONV

YRANGE

ZBUFFER

ZCOORD_CONV

ZERO_OPACITY_SKIP

ZRANGE

In addition, objects of this class inherit:

ALL

An anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values.

Note: The fields of this structure may change in subsequent releases of IDL.

Note: This structure returns COLOR, DEPTH_TEST_DISABLE, DEPTH_TEST_FUNCTION, and DEPTH_WRITE_DISABLE properties that are consistent with other graphic objects. However, these properties are not used by the IDLgrVolume object.

Property Type

Structure

Name String

not displayed

Get: Yes

Set: No

Init: No

Registered: No

ALPHA_CHANNEL

Apply to the volume only when the volume is rendered with a destination rendering quality setting of Low (0). In the case, the volume is rendered as a wireframe cube. Set this property to a floating-point value in the range [0.0, 1.0] to specify the opacity of the wireframe cube. The default value of 1.0 causes IDL to draw the wireframe cube completely opaque. If the value of this property is less than 1.0, then the pixels of the wireframe cube are blended with the pixels already on the screen, where the color of the wireframe cube is multiplied by the alpha value and the pixels already on the screen are multiplied by 1.0-alpha.

Because an object can only be blended with objects already drawn on the screen, the drawing order of the objects must be considered carefully in order to obtain the desired results.

This property has no effect on devices using indexed color mode.

Property Type

Float-point value

Name String

Transparency

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

AMBIENT

The color and intensity of the volume’s base ambient lighting. Color is specified as a three-element vector [red, green, blue]. The default is [255, 255, 255]. AMBIENT is applicable only when LIGHTING_MODEL is set.

In a property sheet, this property appears as a color property.

Property Type

COLOR

Name String

Ambient color

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

BOUNDS

A six-element floating-point vector of the form [xmin, ymin, zmin, xmax, ymax, zmax], which represents the sub-volume to be rendered. .

This property is registered as a user-defined property, but it is hidden by default.

Property Type

USERDEF

Name String

Subvolume bounds

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

CLIP_PLANES

A 4-by-N floating-point array that specifies the coefficients of the clipping planes to be applied to this object. The four coefficients for each clipping plane are of the form [A, B, C, D], where Ax + By + Cz + D = 0. Portions of this object that fall in the half space Ax + By + Cz + D > 0 will be clipped. By default, the value of this property is a scalar (-1) indicating that no clipping planes are to be applied.

Note: The clipping planes specified via this property are applied in addition to the near and far clipping planes associated with the IDLgrView in which this object appears.

Note: Clipping planes are applied in the data space of this object (prior to the application of any x, y, or z coordinate conversion).

Note: To determine the maximum number of clipping planes supported by the device, use the MAX_NUM_CLIP_PLANES property of the GetDeviceInfo method for the IDLgrBuffer, IDLgrClipboard, IDLgrWindow, and IDLgrVRML objects.

Note: Clipping planes are equivalent to the obsolete cutting planes. If defined, CUTTING_PLANES will be applied first, then the CLIP_PLANES (until a maximum number of planes is reached).

Property Type

Floating-point array

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

COMPOSITE_FUNCTION

An integer value or enumerated list item that determines the composite function to be used to measure the value of a pixel on the viewing plane by analyzing the voxels falling along the corresponding ray. Specify one of the following compositing functions:

Value

Property Sheet Value

Description

0

Alpha blending

The recursive equation

dest' = src * srcalpha +    dest * (1 - srcalpha)

is used to compute the final pixel color (the default).

1

Maximum intensity projection

The color of each pixel on the viewing plane is determined by the voxel with the highest opacity value along the corresponding ray.

2

Alpha sum

The recursive equation

dest' = src + dest *    ( 1 - srcalpha)

is used to compute the final pixel color. This equation assumes that the color tables have been pre-multiplied by the opacity tables. The accumulated values can be no greater than 255.

3

Average intensity

The resulting image is the average of all voxels along the corresponding ray. Disables lighting and only works with grey scale palettes. Will not work with four-channel volumes.

 

Property Type

ENUMLIST

Name String

Composite function

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

DATA0

A three-dimensional array of any type of the format (dx, dy, dz), which specifies a data volume. If the data volume dimensions do not match those of any pre-existing data in DATA1, DATA2, or DATA3, all existing data is removed from the object. See Note On Maximum Renderable Volume Size for additional details.

Specifying this property is the same as specifying the optional vol0 argument to the IDLgrVolume::Init method.

Note: IDL converts and stores volume data in a BYTE array. Thus, all incoming volume data is converted to BYTE type. This could alter the volume data values if the incoming data cannot accurately be stored as BYTE data.

Property Type

Array of any type

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

DATA1

A three-dimensional array of any type of the format (dx, dy, dz), which specifies a data volume. If the data volume dimensions do not match those of any pre-existing data in DATA0, DATA2, or DATA3, all existing data is removed from the object. See Note On Maximum Renderable Volume Size for additional details.

Specifying this property is the same as specifying the optional vol1 argument to the IDLgrVolume::Init method.

Note: IDL converts and stores volume data in a BYTE array. Thus, all incoming volume data is converted to BYTE type. This could alter the volume data values if the incoming data cannot accurately be stored as BYTE data.

Property Type

Array of any type

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

DATA2

A three-dimensional array of any type of the format (dx, dy, dz), which specifies a data volume. If the data volume dimensions do not match those of any pre-existing data in DATA0, DATA1, or DATA3, all existing data is removed from the object.

Specifying this property is the same as specifying the optional vol2argument to the IDLgrVolume::Init method.

Note: IDL converts and stores volume data in a BYTE array. Thus, all incoming volume data is converted to BYTE type. This could alter the volume data values if the incoming data cannot accurately be stored as BYTE data.

Property Type

Array of any type

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

DATA3

A three-dimensional array of any type of the format (dx, dy, dz), which specifies a data volume. If the data volume dimensions do not match those of any pre-existing data in DATA0, DATA1, or DATA2, all existing data is removed from the object.

Specifying this property is the same as specifying the optional vol3 argument to the IDLgrVolume::Init method.

Note: DATA0, DATA1, DATA2, and DATA3 sizes are dynamic.

Note: IDL converts and stores volume data in a BYTE array. Thus, all incoming volume data is converted to BYTE type. This could alter the volume data values if the incoming data cannot accurately be stored as BYTE data.

Property Type

Array of any type

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

DEPTH_CUE

A two-element floating-point array [zbright, zdim] specifying the near and far Z planes between which depth cueing is in effect. Depth cueing is only honored when drawing to a destination object that uses the RGB color model.

Depth cueing causes an object to appear to fade into the background color of the view object with changes in depth. If the depth of an object is further than zdim (that is, if the object’s location in the Z direction is farther from the origin than the value specified by zdim), the object will be painted in the background color.

Similarly, if the object is closer than the value of zbright, the object will appear in its “normal” color. Anywhere in-between, the object will be a blend of the background color and the object color. For example, if the DEPTH_CUE property is set to [-1,1], an object at the depth of 0.0 will appear as a 50% blend of the object color and the view color.

The relationship between Zbrightand Zdim determines the result of the rendering:

You can disable depth cueing by setting zbright = zdim. The default is [0.0, 0.0].

This property is registered as a user-defined property, but it is hidden by default.

Property Type

USERDEF

Name String

Depth cue range

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

HIDE

A Boolean value or enumerated list item indicating whether this object should be drawn:

Value

Property Sheet Value

Description

0

True

Draw graphic (the default)

1

False

Do not draw graphic

 

Property Type

ENUMLIST

Name String

Show

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

HINTS

An integer value or enumerated list item that specifies one of the following acceleration hints:

Value

Property Sheet Value

Description

0

Disable

Disables all acceleration hints (the default).

1

Euclidean distance map (EDM)

Enables Euclidean distance map (EDM) acceleration. This option generates a volume map containing the distance from any voxel to the nearest non-zero opacity voxel. The map is used to speed ray casting by allowing the ray to jump over open spaces. It is most useful with sparse volumes. After setting the EDM hint, the draw operation generates the volume map; this process can take some time. Subsequent draw operations will reuse the generated map and may be much faster, depending on the volume’s sparseness. A new map is not automatically generated to match changes in opacity tables or volume data (for performance reasons). The user may force recomputation of the EDM map by setting the HINTS property to 1 again.

2

Multiple CPU

Enables the use of multiple CPUs for volume rendering if the platforms used support such use. If HINTS is set to 2, IDL will use all the available CPU cores to render portions of the volume in parallel.

3

EDM and Multiple CPU

Selects the two acceleration options described above

Property Type

ENUMLIST

Name String

Acceleration hints

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

INTERPOLATE

A Boolean value or enumerated list item that determines whether the interpolation method.

Value

Property Sheet Value

Description

0

Nearest neighbor

Values between the voxels are estimated using nearest neighbor sampling (the default).

1

Trilinear

Values for each step on a ray are computed from the eight nearest values. Setting this property improves quality at the cost of more computing time, especially when the volume has low resolution with respect to the size of the viewing plane.

Property Type

ENUMLIST

Name String

Interpolation

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

LIGHTING_MODEL

A Boolean value that determines whether to use the current lighting model during rendering in conjunction with a local gradient evaluation.

Note: Only DIRECTIONAL light sources are honored by the volume object. Because normals must be computed for all voxels in a lighted view, enabling light sources increases the rendering time.

Property Type

Boolean

Name String

Use lighting

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

OPACITY_TABLE0

A 256-element byte array that specifies the opacity table for DATA0. The default table is the linear ramp.

Property Type

Byte array

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

OPACITY_TABLE1

A 256-element byte array that specifies the opacity table for DATA1. The default table is the linear ramp. This table is used only when VOLUME_SELECT is set equal to 1.

Property Type

Byte array

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

Property Type

USERDEF

Name String

Color palette

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

PARENT

An object reference to the object that contains this object.

Property Type

Object reference

Name String

not displayed

Get: Yes

Set: No

Init: No

Registered: No

REGISTER_PROPERTIES

A Boolean value that determines whether to register properties available for this object. If this property is set, all properties marked in this properties section as “Registered: Yes” will be registered for display in a property sheet. This property is useful mainly when creating iTools. By default, no properties are registered.

Property Type

Boolean

Name String

not displayed

Get: No

Set: No

Init: Yes

Registered: No

RENDER_STEP

A three-element floating-point vector of the form [x, y, z] that specifies the stepping factor through the voxel matrix.

This property is registered as a user-defined property, but it is hidden by default.

Property Type

USERDEF

Name String

XYZ render step

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

RGB_TABLE0

A 256 x 3-element byte array that specifies the RGB color table for DATA0. The default table is the linear ramp. .

Property Type

Byte array

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

RGB_TABLE1

A 256 x 3-element byte array that specifies the RGB color table for DATA1. The default table is the linear ramp. This table is used only when VOLUME_SELECT is set equal to 1.

Property Type

Byte array

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

SHADER

An object reference to an IDLgrShader object (or an object containing IDLgrShader as a superclass). When there is suitable graphics card hardware support, the volume is rendered using the GLSL shader program (executed on the graphics card) instead of using fixed OpenGL properties when initially drawn. (If a suitable graphics card is not present, IDL ignores the shader object when the scene is drawn.) A single IDLgrShader object may be associated with additional volume objects or other graphic objects that have the SHADER property.

Property Type

Object reference

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

TWO_SIDED

A Boolean value or an enumerated list item that determines whether the lighting model uses a two-sided voxel gradient.

Value

Property Sheet Value

Description

0

One-sided

The default.

1

Two-sided

Differs from one-sided in that this method uses the absolute value of the inner product of the light direction and the surface gradient instead of clamping to 0.0 for negative values.

Property Type

ENUMLIST

Name String

Voxel gradient

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

VALID_DATA

An integer array (one per volume, DATA0, DATA1, etc.) which have the value 1 if volume data has been loaded for that volume and 0 if that volume data is currently undefined.

Property Type

Integer array

Name String

not displayed

Get: Yes

Set: No

Init: No

Registered: No

VOLUME_SELECT

An integer value that selects how the volume data (DATA0, DATA1, DATA2, DATA3) is combined to form the src and srcalpha parameters described in the COMPOSITE_FUNCTION function property.

The volume data is always stored and treated as 8-bit indices into the RGB and opacity tables.

Set the RGB and/or opacity tables to linear ramps to use the volume data as direct color or opacity values. Accepted values are:

0

Render single volume from DATA0. This is the default. The value at voxel [i,j,k] would be computed as:

srcRed[i,j,k] = RGB_TABLE0[DATA0[i,j,k],0]

srcGreen[i,j,k] = RGB_TABLE0[DATA0[i,j,k],1]

srcBlue[i,j,k] = RGB_TABLE0[DATA0[i,j,k],2]

srcAlpha[i,j,k] = OPACITY_TABLE0[DATA0[i,j,k]]

1

Render dual volume from DATA0 and DATA1. The value at voxel [i,j,k] is modulated between the two data sets as follows:

srcRed[i,j,k] = (RGB_TABLE0[DATA0[i,j,k],0] *

                 RGB_TABLE1[DATA1[i,j,k],0]) / 255

srcGreen[i,j,k] = (RGB_TABLE0[DATA0[i,j,k],1] *

                   RGB_TABLE1[DATA1[i,j,k],1]) / 255

srcBlue[i,j,k] = (RGB_TABLE0[DATA0[i,j,k],2] *

                  RGB_TABLE1[DATA1[i,j,k],2]) / 255

srcAlpha[i,j,k] = (OPACITY_TABLE0[DATA0[i,j,k]] *

                   OPACITY_TABLE1[DATA1[i,j,k]]) / 255

2

Render RGBA volume from DATA0 (red), DATA1 (green), DATA2 (blue), and DATA3 (alpha). The value at voxel [i,j,k] would be computed as:

srcRed[i,j,k] = RGB_TABLE0[DATA0[i,j,k],0]

srcGreen[i,j,k] = RGB_TABLE0[DATA1[i,j,k],1]

srcBlue[i,j,k] = RGB_TABLE0[DATA2[i,j,k],2]

srcAlpha[i,j,k] = OPACITY_TABLE0[DATA3[i,j,k]]

Property Type

Integer

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

XCOORD_CONV

A floating-point vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows:

NormalizedX = s0 + s1 * DataX

Recommended values are:

[(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)]

The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double-precision floating-point.

Property Type

Floating-point vector

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

XRANGE

A two-element double-precision floating-point vector of the form [xmin, xmax] that specifies the range of x data coordinates covered by the graphic object.

Property Type

Floating-point vector

Name String

not displayed

Get: Yes

Set: No

Init: No

Registered: No

YCOORD_CONV

A floating-point vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows:

NormalizedY = s0 + s1 * DataY

Recommended values are:

[(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)]

The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double-precision floating-point.

Property Type

Floating-point vector

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

YRANGE

A two-element double-precision floating-point vector of the form [ymin, ymax] that specifies the range of y data coordinates covered by the graphic object.

Property Type

Floating-point vector

Name String

not displayed

Get: Yes

Set: No

Init: No

Registered: No

ZBUFFER

A Boolean value that determines whether to clip the rendering to the current Z-buffer and then update the buffer. The default is to not modify the current Z-buffer.

Property Type

Boolean

Name String

Update Z buffer

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

ZCOORD_CONV

A floating-point vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows:

NormalizedZ = s0 + s1 * DataZ

Recommended values are:

[(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)]

The default is [0.0, 1.0]IDL converts, maintains, and returns this data as double-precision floating-point.

Property Type

Floating-point vector

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

ZERO_OPACITY_SKIP

A Boolean value that determines whether to skip voxels with an opacity of 0. This property can increase the output contrast of MIP (MAXIMUM_INTENSITY) projections by allowing the background to show through. If this property is set, voxels with an opacity of zero will not modify the Z-buffer. The default (not setting the property) continues to render voxels with an opacity of zero.

Property Type

Boolean

Name String

Skip zero opacity

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

ZRANGE

A two-element double-precision floating-point vector of the form [zmin, zmax] that specifies the range of z data coordinates covered by the graphic object.

Property Type

Floating-point vector

Name String

not displayed

Get: Yes

Set: No

Init: No

Registered: No