API reference - Class Image
Notation used in Ruby API documentation
Description: An image to be stored as a layout annotation
Class hierarchy: Image
- Public constructors
- Public methods
- Deprecated methods (protected, public, static, non-static and constructors)
- Detailed description
Images can be put onto the layout canvas as annotations, along with rulers and markers. Images can be monochrome (represent scalar data) as well as color (represent color images). The display of images can be adjusted in various ways, i.e. color mapping (translation of scalar values to colors), geometrical transformations (including rotation by arbitrary angles) and similar. Images are always based on floating point data. The actual data range is not fixed and can be adjusted to the data set (i.e. 0..255 or -1..1). This gives a great flexibility when displaying data which is the result of some measurement or calculation for example. The basic parameters of an image are the width and height of the data set, the width and height of one pixel, the geometrical transformation to be applied, the data range (min_value to max_value) and the data mapping which is described by an own class, ImageDataMapping.
Starting with version 0.22, the basic transformation is a 3x3 matrix rather than the simple affine transformation. This matrix includes the pixel dimensions as well. One consequence of that is that the magnification part of the matrix and the pixel dimensions are no longer separated. That has certain consequences, i.e. setting an affine transformation with a magnification scales the pixel sizes as before but an affine transformation returned will no longer contain the pixel dimensions as magnification because it only supports isotropic scaling. For backward compatibility, the rotation center for the affine transformations while the default center and the center for matrix transformations is the image center.
As with version 0.25, images become 'live' objects. Changes to image properties will be reflected in the view automatically once the image object has been inserted into a view. Note that changes are not immediately reflected in the view, but are delayed until the view is refreshed. Hence, iterating the view's images will not render the same results than the image objects attached to the view. To ensure synchonization, call Image#update.
Public constructors
| new Image ptr | new | Create a new image with the default attributes | |
| new Image ptr | new | (string filename) | Constructor from a image file |
| new Image ptr | new | (string filename, const DCplxTrans trans) | Constructor from a image file |
| new Image ptr | new | (unsigned long w, unsigned long h, double[] data) | Constructor for a monochrome image with the given pixel values |
| new Image ptr | new | (unsigned long w, unsigned long h, const DCplxTrans trans, double[] data) | Constructor for a monochrome image with the given pixel values |
| new Image ptr | new | (unsigned long w, unsigned long h, double[] red, double[] green, double[] blue) | Constructor for a color image with the given pixel values |
| new Image ptr | new | (unsigned long w, unsigned long h, const DCplxTrans trans, double[] red, double[] green, double[] blue) | Constructor for a color image with the given pixel values |
Public methods
| void | _create | Ensures the C++ object is created | ||
| void | _destroy | Explicitly 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 | _manage | Marks the object as managed by the script side. | ||
| void | _unmanage | Marks the object as no longer owned by the script side. | ||
| void | assign | (const Image other) | Assigns another object to self | |
| [const] | DBox | box | Gets the bounding box of the image | |
| [const] | ImageDataMapping | data_mapping | Gets the data mapping | |
| void | data_mapping= | (const ImageDataMapping data_mapping) | Sets the data mapping object | |
| void | delete | Deletes this image from the view | ||
| void | detach | Detaches the image object from the view | ||
| [const] | new Image ptr | dup | Creates a copy of self | |
| [const] | string | filename | Gets the name of the file loaded of an empty string if not file is loaded | |
| [const] | double | get_pixel | (unsigned long x, unsigned long y) | Gets one pixel (monochrome only) |
| [const] | double | get_pixel | (unsigned long x, unsigned long y, unsigned int component) | Gets one pixel (monochrome and color) |
| [const] | unsigned long | height | Gets the height of the image in pixels | |
| [const] | unsigned long | id | Gets the Id | |
| [const] | bool | is_color? | Returns true, if the image is a color image | |
| [const] | bool | is_empty? | Returns true, if the image does not contain any data (i.e. is default constructed) | |
| [const] | bool | is_valid? | Returns a value indicating whether the object is a valid reference. | |
| [const] | bool | is_visible? | Gets a flag indicating whether the image object is visible | |
| [const] | bool | mask | (unsigned long x, unsigned long y) | Gets the mask for one pixel |
| [const] | Matrix3d | matrix | Returns the pixel-to-micron transformation matrix | |
| void | matrix= | (const Matrix3d t) | Sets the transformation matrix | |
| [const] | double | max_value | Sets the maximum value | |
| void | max_value= | (double v) | Gets the upper limit of the values in the data set | |
| [const] | double | min_value | Gets the upper limit of the values in the data set | |
| void | min_value= | (double v) | Sets the minimum value | |
| [const] | double | pixel_height | Gets the pixel height | |
| void | pixel_height= | (double h) | Sets the pixel height | |
| [const] | double | pixel_width | Gets the pixel width | |
| void | pixel_width= | (double w) | Sets the pixel width | |
| void | set_data | (unsigned long w, unsigned long h, double[] d) | Writes the image data field (monochrome) | |
| void | set_data | (unsigned long w, unsigned long h, double[] r, double[] g, double[] b) | Writes the image data field (color) | |
| void | set_mask | (unsigned long x, unsigned long y, bool m) | Sets the mask for a pixel | |
| void | set_pixel | (unsigned long x, unsigned long y, double v) | Sets one pixel (monochrome) | |
| void | set_pixel | (unsigned long x, unsigned long y, double r, double g, double b) | Sets one pixel (color) | |
| [const] | string | to_s | Converts the image to a string | |
| [const] | DCplxTrans | trans | Returns the pixel-to-micron transformation | |
| void | trans= | (const DCplxTrans t) | Sets the transformation | |
| [const] | Image | transformed | (const DTrans t) | Transforms the image with the given simple transformation |
| [const] | Image | transformed | (const Matrix3d t) | Transforms the image with the given matrix transformation |
| [const] | Image | transformed | (const DCplxTrans t) | Transforms the image with the given complex transformation |
| void | update | Forces an update of the view | ||
| void | visible= | (bool v) | Sets the visibility | |
| [const] | unsigned long | width | Gets the width of the image in pixels | |
| [const] | int | z_position | Gets the z position of the image | |
| void | z_position= | (int z) | Sets the z position of the image |
Deprecated methods (protected, public, static, non-static and constructors)
| void | create | Use of this method is deprecated. Use _create instead | ||
| void | destroy | Use of this method is deprecated. Use _destroy instead | ||
| [const] | bool | destroyed? | Use of this method is deprecated. Use _destroyed? instead | |
| [const] | bool | is_const_object? | Use of this method is deprecated. Use _is_const_object? instead | |
| [const] | Image | transformed_cplx | (const DCplxTrans t) | Use of this method is deprecated. Use transformed instead |
| [const] | Image | transformed_matrix | (const Matrix3d t) | Use of this method is deprecated. Use transformed instead |
Detailed description
_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. | |||||||||||
assign | Signature: void assign (const Image other) Description: Assigns another object to self | |||||||||||
box | Signature: [const] DBox box Description: Gets the bounding box of the image
| |||||||||||
create | Signature: void create Description: Ensures the C++ object is created Use of this method is deprecated. Use _create instead | |||||||||||
data_mapping | Signature: [const] ImageDataMapping data_mapping Description: Gets the data mapping
The data mapping describes the transformation of a pixel value (any double value) into pixel data which can be sent to the graphics cards for display. See ImageDataMapping for a more detailed description. Python specific notes: | |||||||||||
data_mapping= | Signature: void data_mapping= (const ImageDataMapping data_mapping) Description: Sets the data mapping object The data mapping describes the transformation of a pixel value (any double value) into pixel data which can be sent to the graphics cards for display. See ImageDataMapping for a more detailed description. Python specific notes: | |||||||||||
delete | Signature: void delete Description: Deletes this image from the view If the image is an "active" one, this method will remove it from the view. This object will become detached and can still be manipulated, but without having an effect on the view. This method has been introduced in version 0.25. | |||||||||||
destroy | Signature: void destroy Description: Explicitly destroys the object Use of this method is deprecated. Use _destroy instead | |||||||||||
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 | |||||||||||
detach | Signature: void detach Description: Detaches the image object from the view If the image object was inserted into the view, property changes will be reflected in the view. To disable this feature, 'detach'' can be called after which the image object becomes inactive and changes will no longer be reflected in the view. This method has been introduced in version 0.25. | |||||||||||
dup | Signature: [const] new Image ptr dup Description: Creates a copy of self | |||||||||||
filename | Signature: [const] string filename Description: Gets the name of the file loaded of an empty string if not file is loaded
| |||||||||||
get_pixel | Signature: [const] double get_pixel (unsigned long x,unsigned long y) Description: Gets one pixel (monochrome only)
If x or y value exceeds the image bounds, this method returns 0.0. This method is valid for monochrome images only. For color images it will return 0.0 always. Use is_color? to decide whether the image is a color image or monochrome one. | |||||||||||
Signature: [const] double get_pixel (unsigned long x,unsigned long y,unsigned int component) Description: Gets one pixel (monochrome and color)
If the component index, x or y value exceeds the image bounds, this method returns 0.0. For monochrome images, the component index is ignored. | ||||||||||||
height | Signature: [const] unsigned long height Description: Gets the height of the image in pixels
| |||||||||||
id | Signature: [const] unsigned long id Description: Gets the Id The Id is an arbitrary integer that can be used to track the evolution of an image object. The Id is not changed when the object is edited. On initialization, a unique Id is given to the object. The Id cannot be changed. This behaviour has been modified in version 0.20. | |||||||||||
is_color? | Signature: [const] bool is_color? Description: Returns true, if the image is a color image
| |||||||||||
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 | |||||||||||
is_empty? | Signature: [const] bool is_empty? Description: Returns true, if the image does not contain any data (i.e. is default constructed)
| |||||||||||
is_valid? | Signature: [const] bool is_valid? Description: Returns a value indicating whether the object is a valid reference. If this value is true, the object represents an image on the screen. Otherwise, the object is a 'detached' image which does not have a representation on the screen. This method was introduced in version 0.25. | |||||||||||
is_visible? | Signature: [const] bool is_visible? Description: Gets a flag indicating whether the image object is visible An image object can be made invisible by setting the visible property to false. This method has been introduced in version 0.20. | |||||||||||
mask | Signature: [const] bool mask (unsigned long x,unsigned long y) Description: Gets the mask for one pixel
See set_mask for details about the mask. This method has been introduced in version 0.23. | |||||||||||
matrix | Signature: [const] Matrix3d matrix Description: Returns the pixel-to-micron transformation matrix This transformation matrix converts pixel coordinates (0,0 being the center and each pixel having the dimension of pixel_width and pixel_height) to micron coordinates. The coordinate of the pixel is the lower left corner of the pixel. The matrix is more general than the transformation used before and supports shear and perspective transformation. This property replaces the trans property which is still functional, but deprecated. This method has been introduced in version 0.22. Python specific notes: | |||||||||||
matrix= | Signature: void matrix= (const Matrix3d t) Description: Sets the transformation matrix This transformation matrix converts pixel coordinates (0,0 being the center and each pixel having the dimension of pixel_width and pixel_height) to micron coordinates. The coordinate of the pixel is the lower left corner of the pixel. The matrix is more general than the transformation used before and supports shear and perspective transformation. This property replaces the trans property which is still functional, but deprecated. This method has been introduced in version 0.22. Python specific notes: | |||||||||||
max_value | Signature: [const] double max_value Description: Sets the maximum value See the max_value method for the description of the maximum value property. Python specific notes: | |||||||||||
max_value= | Signature: void max_value= (double v) Description: Gets the upper limit of the values in the data set This value determines the upper end of the data mapping (i.e. white value etc.). It does not necessarily correspond to the maximum value of the data set but it must be larger than that. Python specific notes: | |||||||||||
min_value | Signature: [const] double min_value Description: Gets the upper limit of the values in the data set This value determines the upper end of the data mapping (i.e. white value etc.). It does not necessarily correspond to the minimum value of the data set but it must be larger than that. Python specific notes: | |||||||||||
min_value= | Signature: void min_value= (double v) Description: Sets the minimum value See min_value for the description of the minimum value property. Python specific notes: | |||||||||||
new | Signature: [static] new Image ptr new Description: Create a new image with the default attributes This will create an empty image without data and no particular pixel width or related. Use the read_file or set_data methods to set image properties and pixel values. Python specific notes: | |||||||||||
Signature: [static] new Image ptr new (string filename) Description: Constructor from a image file
This constructor creates an image object from a file (which can have any format supported by Qt) and a unit transformation. The image will originally be put to position 0,0 (lower left corner) and each pixel will have a size of 1 (micron). Python specific notes: | ||||||||||||
Signature: [static] new Image ptr new (string filename,const DCplxTrans trans) Description: Constructor from a image file
This constructor creates an image object from a file (which can have any format supported by Qt) and a transformation. The image will originally be put to position 0,0 (lower left corner) and each pixel will have a size of 1. The transformation describes how to transform this image into micron space. Python specific notes: | ||||||||||||
Signature: [static] new Image ptr new (unsigned long w,unsigned long h,double[] data) Description: Constructor for a monochrome image with the given pixel values
This constructor creates an image from the given pixel values. The values have to be organized line by line. Each line must consist of "w" values where the first value is the leftmost pixel. Note, that the rows are oriented in the mathematical sense (first one is the lowest) contrary to the common convention for image data. Initially the pixel width and heigt will be 1 micron and the data range will be 0 to 1.0 (black to white level). To adjust the data range use the min_value and max_value properties. Python specific notes: | ||||||||||||
Signature: [static] new Image ptr new (unsigned long w,unsigned long h,const DCplxTrans trans,double[] data) Description: Constructor for a monochrome image with the given pixel values
This constructor creates an image from the given pixel values. The values have to be organized line by line. Each line must consist of "w" values where the first value is the leftmost pixel. Note, that the rows are oriented in the mathematical sense (first one is the lowest) contrary to the common convention for image data. Initially the pixel width and heigt will be 1 micron and the data range will be 0 to 1.0 (black to white level). To adjust the data range use the min_value and max_value properties. Python specific notes: | ||||||||||||
Signature: [static] new Image ptr new (unsigned long w,unsigned long h,double[] red,double[] green,double[] blue) Description: Constructor for a color image with the given pixel values
This constructor creates an image from the given pixel values. The values have to be organized line by line and separated by color channel. Each line must consist of "w" values where the first value is the leftmost pixel. Note, that the rows are oriented in the mathematical sense (first one is the lowest) contrary to the common convention for image data. Initially the pixel width and heigt will be 1 micron and the data range will be 0 to 1.0 (black to white level). To adjust the data range use the min_value and max_value properties. Python specific notes: | ||||||||||||
Signature: [static] new Image ptr new (unsigned long w,unsigned long h,const DCplxTrans trans,double[] red,double[] green,double[] blue) Description: Constructor for a color image with the given pixel values
This constructor creates an image from the given pixel values. The values have to be organized line by line and separated by color channel. Each line must consist of "w" values where the first value is the leftmost pixel. Note, that the rows are oriented in the mathematical sense (first one is the lowest) contrary to the common convention for image data. Initially the pixel width and heigt will be 1 micron and the data range will be 0 to 1.0 (black to white level). To adjust the data range use the min_value and max_value properties. Python specific notes: | ||||||||||||
pixel_height | Signature: [const] double pixel_height Description: Gets the pixel height See pixel_height= for a description of that property. Starting with version 0.22, this property is incorporated into the transformation matrix. This property is provided for convenience only. Python specific notes: | |||||||||||
pixel_height= | Signature: void pixel_height= (double h) Description: Sets the pixel height The pixel height determines the height of on pixel in the original space which is transformed to micron space with the transformation. Starting with version 0.22, this property is incorporated into the transformation matrix. This property is provided for convenience only. Python specific notes: | |||||||||||
pixel_width | Signature: [const] double pixel_width Description: Gets the pixel width See pixel_width= for a description of that property. Starting with version 0.22, this property is incorporated into the transformation matrix. This property is provided for convenience only. Python specific notes: | |||||||||||
pixel_width= | Signature: void pixel_width= (double w) Description: Sets the pixel width The pixel width determines the width of on pixel in the original space which is transformed to micron space with the transformation. Starting with version 0.22, this property is incorporated into the transformation matrix. This property is provided for convenience only. Python specific notes: | |||||||||||
set_data | Signature: void set_data (unsigned long w,unsigned long h,double[] d) Description: Writes the image data field (monochrome)
See the constructor description for the data organisation in that field. | |||||||||||
Signature: void set_data (unsigned long w,unsigned long h,double[] r,double[] g,double[] b) Description: Writes the image data field (color)
See the constructor description for the data organisation in that field. | ||||||||||||
set_mask | Signature: void set_mask (unsigned long x,unsigned long y,bool m) Description: Sets the mask for a pixel
If the mask of a pixel is set to false, the pixel is not drawn. The default is true for all pixels. This method has been introduced in version 0.23. | |||||||||||
set_pixel | Signature: void set_pixel (unsigned long x,unsigned long y,double v) Description: Sets one pixel (monochrome)
If the component index, x or y value exceeds the image bounds of the image is a color image, this method does nothing. | |||||||||||
Signature: void set_pixel (unsigned long x,unsigned long y,double r,double g,double b) Description: Sets one pixel (color)
If the component index, x or y value exceeds the image bounds of the image is not a color image, this method does nothing. | ||||||||||||
to_s | Signature: [const] string to_s Description: Converts the image to a string
Python specific notes: | |||||||||||
trans | Signature: [const] DCplxTrans trans Description: Returns the pixel-to-micron transformation This transformation converts pixel coordinates (0,0 being the lower left corner and each pixel having the dimension of pixel_width and pixel_height) to micron coordinates. The coordinate of the pixel is the lower left corner of the pixel. The general property is matrix which also allows perspective and shear transformation. This property will only work, if the transformation does not include perspective or shear components. Therefore this property is deprecated. Please note that for backward compatibility, the rotation center is pixel 0,0 (lowest left one), while it is the image center for the matrix transformation. Python specific notes: | |||||||||||
trans= | Signature: void trans= (const DCplxTrans t) Description: Sets the transformation This transformation converts pixel coordinates (0,0 being the lower left corner and each pixel having the dimension of pixel_width and pixel_height) to micron coordinates. The coordinate of the pixel is the lower left corner of the pixel. The general property is matrix which also allows perspective and shear transformation. Please note that for backward compatibility, the rotation center is pixel 0,0 (lowest left one), while it is the image center for the matrix transformation. Python specific notes: | |||||||||||
transformed | Signature: [const] Image transformed (const DTrans t) Description: Transforms the image with the given simple transformation
| |||||||||||
Signature: [const] Image transformed (const Matrix3d t) Description: Transforms the image with the given matrix transformation
This method has been introduced in version 0.22. | ||||||||||||
Signature: [const] Image transformed (const DCplxTrans t) Description: Transforms the image with the given complex transformation
| ||||||||||||
transformed_cplx | Signature: [const] Image transformed_cplx (const DCplxTrans t) Description: Transforms the image with the given complex transformation
Use of this method is deprecated. Use transformed instead | |||||||||||
transformed_matrix | Signature: [const] Image transformed_matrix (const Matrix3d t) Description: Transforms the image with the given matrix transformation
Use of this method is deprecated. Use transformed instead | |||||||||||
update | Signature: void update Description: Forces an update of the view Usually it is not required to call this method. The image object is automatically synchronized with the view's image objects. For performance reasons this update is delayed to collect multiple update requests. Calling 'update' will ensure immdiate updates. This method has been introduced in version 0.25. | |||||||||||
visible= | Signature: void visible= (bool v) Description: Sets the visibility See the is_visible? method for a description of this property. This method has been introduced in version 0.20. Python specific notes: | |||||||||||
width | Signature: [const] unsigned long width Description: Gets the width of the image in pixels
| |||||||||||
z_position | Signature: [const] int z_position Description: Gets the z position of the image Images with a higher z position are painted in front of images with lower z position. The z value is an integer that controls the position relative to other images. This method was introduced in version 0.25. Python specific notes: | |||||||||||
z_position= | Signature: void z_position= (int z) Description: Sets the z position of the image See z_position for details about the z position attribute. This method was introduced in version 0.25. Python specific notes: |