Routines (alphabetical) > Object Classes > Graphics Object Classes > IDLgrVolume Properties

# 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 About 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:

- IDLitComponent

### 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:

- Zbright < Zdim: Rendering darkens with depth.
- Zbright > Zdim: Rendering brightens with depth.
- Zbright = Zdim: Disables depth cueing.

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