API reference - Class ImageDataMapping

Notation used in Ruby API documentation

Module: lay

Description: A structure describing the data mapping of an image object

Data mapping is the process of transforming the data into RGB pixel values. This implementation provides four adjustment steps: first, in the case of monochrome data, the data is converted to a RGB triplet using the color map. The default color map will copy the value to all channels rendering a gray scale. After having normalized the data to 0..1 cooresponding to the min_value and max_value settings of the image, a color channel-independent brightness and contrast adjustment is applied. Then, a per-channel multiplier (red_gain, green_gain, blue_gain) is applied. Finally, the gamma function is applied and the result converted into a 0..255 pixel value range and clipped.

Public constructors

new ImageDataMapping ptrnewCreate a new data mapping object with default settings

Public methods

[const]ImageDataMapping ptr_const_castReturns a non-const reference to self.
void_createEnsures the C++ object is created
void_destroyExplicitly destroys the object
[const]bool_destroyed?Returns a value indicating whether the object was already destroyed
[const]bool_is_const_object?Returns a value indicating whether the reference is a const reference
void_manageMarks the object as managed by the script side.
void_unmanageMarks the object as no longer owned by the script side.
voidadd_colormap_entry(double value,
unsigned int color)
Add a colormap entry for this data mapping object.
voidadd_colormap_entry(double value,
unsigned int lcolor,
unsigned int rcolor)
Add a colormap entry for this data mapping object.
voidassign(const ImageDataMapping other)Assigns another object to self
[const]doubleblue_gainThe blue channel gain
voidblue_gain=(double blue_gain)Set the blue_gain
[const]doublebrightnessThe brightness value
voidbrightness=(double brightness)Set the brightness
voidclear_colormapThe the color map of this data mapping object.
[const]unsigned intcolormap_color(unsigned long n)Returns the color for a given color map entry.
[const]unsigned intcolormap_lcolor(unsigned long n)Returns the left-side color for a given color map entry.
[const]unsigned intcolormap_rcolor(unsigned long n)Returns the right-side color for a given color map entry.
[const]doublecolormap_value(unsigned long n)Returns the value for a given color map entry.
[const]doublecontrastThe contrast value
voidcontrast=(double contrast)Set the contrast
[const]new ImageDataMapping ptrdupCreates a copy of self
[const]doublegammaThe gamma value
voidgamma=(double gamma)Set the gamma
[const]doublegreen_gainThe green channel gain
voidgreen_gain=(double green_gain)Set the green_gain
[const]unsigned longnum_colormap_entriesReturns the current number of color map entries.
[const]doublered_gainThe red channel gain
voidred_gain=(double red_gain)Set the red_gain

Deprecated methods (protected, public, static, non-static and constructors)

voidcreateUse of this method is deprecated. Use _create instead
voiddestroyUse of this method is deprecated. Use _destroy instead
[const]booldestroyed?Use of this method is deprecated. Use _destroyed? instead
[const]boolis_const_object?Use of this method is deprecated. Use _is_const_object? instead

Detailed description

_const_cast

Signature: [const] ImageDataMapping ptr _const_cast

Description: Returns a non-const reference to self.

Basically, this method allows turning a const object reference to a non-const one. This method is provided as last resort to remove the constness from an object. Usually there is a good reason for a const object reference, so using this method may have undesired side effects.

This method has been introduced in version 0.29.6.

_create

Signature: void _create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

_destroy

Signature: void _destroy

Description: Explicitly destroys the object

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

_destroyed?

Signature: [const] bool _destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

_is_const_object?

Signature: [const] bool _is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

_manage

Signature: void _manage

Description: Marks the object as managed by the script side.

After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required.

Usually it's not required to call this method. It has been introduced in version 0.24.

_unmanage

Signature: void _unmanage

Description: Marks the object as no longer owned by the script side.

Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur.

Usually it's not required to call this method. It has been introduced in version 0.24.

add_colormap_entry

(1) Signature: void add_colormap_entry (double value, unsigned int color)

Description: Add a colormap entry for this data mapping object.

value:The value at which the given color should be applied.
color:The color to apply (a 32 bit RGB value).

This settings establishes a color mapping for a given value in the monochrome channel. The color must be given as a 32 bit integer, where the lowest order byte describes the blue component (0 to 255), the second byte the green component and the third byte the red component, i.e. 0xff0000 is red and 0x0000ff is blue.

(2) Signature: void add_colormap_entry (double value, unsigned int lcolor, unsigned int rcolor)

Description: Add a colormap entry for this data mapping object.

value:The value at which the given color should be applied.
lcolor:The color to apply left of the value (a 32 bit RGB value).
rcolor:The color to apply right of the value (a 32 bit RGB value).

This settings establishes a color mapping for a given value in the monochrome channel. The colors must be given as a 32 bit integer, where the lowest order byte describes the blue component (0 to 255), the second byte the green component and the third byte the red component, i.e. 0xff0000 is red and 0x0000ff is blue.

In contrast to the version with one color, this version allows specifying a color left and right of the value - i.e. a discontinuous step.

This variant has been introduced in version 0.27.

assign

Signature: void assign (const ImageDataMapping other)

Description: Assigns another object to self

blue_gain

Signature: [const] double blue_gain

Description: The blue channel gain

This value is the multiplier by which the blue channel is scaled after applying false color transformation and contrast/brightness/gamma.

1.0 is a neutral value. The gain should be >=0.0.

Python specific notes:
The object exposes a readable attribute 'blue_gain'. This is the getter.

blue_gain=

Signature: void blue_gain= (double blue_gain)

Description: Set the blue_gain

See blue_gain for a description of this property.

Python specific notes:
The object exposes a writable attribute 'blue_gain'. This is the setter.

brightness

Signature: [const] double brightness

Description: The brightness value

The brightness is a double value between roughly -1.0 and 1.0. Neutral (original) brightness is 0.0.

Python specific notes:
The object exposes a readable attribute 'brightness'. This is the getter.

brightness=

Signature: void brightness= (double brightness)

Description: Set the brightness

See brightness for a description of this property.

Python specific notes:
The object exposes a writable attribute 'brightness'. This is the setter.

clear_colormap

Signature: void clear_colormap

Description: The the color map of this data mapping object.

colormap_color

Signature: [const] unsigned int colormap_color (unsigned long n)

Description: Returns the color for a given color map entry.

n:The index of the entry (0..num_colormap_entries-1)
Returns:The color (see add_colormap_entry for a description).

NOTE: this version is deprecated and provided for backward compatibility. For discontinuous nodes this method delivers the left-sided color.

colormap_lcolor

Signature: [const] unsigned int colormap_lcolor (unsigned long n)

Description: Returns the left-side color for a given color map entry.

n:The index of the entry (0..num_colormap_entries-1)
Returns:The color (see add_colormap_entry for a description).

This method has been introduced in version 0.27.

colormap_rcolor

Signature: [const] unsigned int colormap_rcolor (unsigned long n)

Description: Returns the right-side color for a given color map entry.

n:The index of the entry (0..num_colormap_entries-1)
Returns:The color (see add_colormap_entry for a description).

This method has been introduced in version 0.27.

colormap_value

Signature: [const] double colormap_value (unsigned long n)

Description: Returns the value for a given color map entry.

n:The index of the entry (0..num_colormap_entries-1)
Returns:The value (see add_colormap_entry for a description).

contrast

Signature: [const] double contrast

Description: The contrast value

The contrast is a double value between roughly -1.0 and 1.0. Neutral (original) contrast is 0.0.

Python specific notes:
The object exposes a readable attribute 'contrast'. This is the getter.

contrast=

Signature: void contrast= (double contrast)

Description: Set the contrast

See contrast for a description of this property.

Python specific notes:
The object exposes a writable attribute 'contrast'. This is the setter.

create

Signature: void create

Description: Ensures the C++ object is created

Use of this method is deprecated. Use _create instead

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

destroy

Signature: void destroy

Description: Explicitly destroys the object

Use of this method is deprecated. Use _destroy instead

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

destroyed?

Signature: [const] bool destroyed?

Description: Returns a value indicating whether the object was already destroyed

Use of this method is deprecated. Use _destroyed? instead

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

dup

Signature: [const] new ImageDataMapping ptr dup

Description: Creates a copy of self

Python specific notes:
This method also implements '__copy__' and '__deepcopy__'.

gamma

Signature: [const] double gamma

Description: The gamma value

The gamma value allows one to adjust for non-linearities in the display chain and to enhance contrast. A value for linear intensity reproduction on the screen is roughly 0.5. The exact value depends on the monitor calibration. Values below 1.0 give a "softer" appearance while values above 1.0 give a "harder" appearance.

Python specific notes:
The object exposes a readable attribute 'gamma'. This is the getter.

gamma=

Signature: void gamma= (double gamma)

Description: Set the gamma

See gamma for a description of this property.

Python specific notes:
The object exposes a writable attribute 'gamma'. This is the setter.

green_gain

Signature: [const] double green_gain

Description: The green channel gain

This value is the multiplier by which the green channel is scaled after applying false color transformation and contrast/brightness/gamma.

1.0 is a neutral value. The gain should be >=0.0.

Python specific notes:
The object exposes a readable attribute 'green_gain'. This is the getter.

green_gain=

Signature: void green_gain= (double green_gain)

Description: Set the green_gain

See green_gain for a description of this property.

Python specific notes:
The object exposes a writable attribute 'green_gain'. This is the setter.

is_const_object?

Signature: [const] bool is_const_object?

Description: Returns a value indicating whether the reference is a const reference

Use of this method is deprecated. Use _is_const_object? instead

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

new

Signature: [static] new ImageDataMapping ptr new

Description: Create a new data mapping object with default settings

Python specific notes:
This method is the default initializer of the object.

num_colormap_entries

Signature: [const] unsigned long num_colormap_entries

Description: Returns the current number of color map entries.

Returns:The number of entries.

red_gain

Signature: [const] double red_gain

Description: The red channel gain

This value is the multiplier by which the red channel is scaled after applying false color transformation and contrast/brightness/gamma.

1.0 is a neutral value. The gain should be >=0.0.

Python specific notes:
The object exposes a readable attribute 'red_gain'. This is the getter.

red_gain=

Signature: void red_gain= (double red_gain)

Description: Set the red_gain

See red_gain for a description of this property.

Python specific notes:
The object exposes a writable attribute 'red_gain'. This is the setter.