img
 Images and Density Maps¶
Introduction : The ImageHandle¶
OpenStructure offers extensive processing capabilities for planar 2d images and
3d maps using the img
module. The main datastructure for images is the
ImageHandle
class.
ImageHandles provide a clean and efficient interface to interact with images and
maps. An ImageHandle
can store an image in either real (SPATIAL
)
or Fourier (FREQUENCY
) space and always keep track of the currently
active domain. This means,for example that one can apply a Fourier
transformation to an ImageHandle
containing a SPATIAL
image and
the image will correctly identify the new active domain as FREQUENCY
.
The ImageHandle
also understands, for example, that applying a
Fourier Transform to a centrosymmetric FREQUENCY
image results in a real
SPATIAL
image, but applying it to a noncentrosymmetric one results in a
complex SPATIAL
image.
Furthermore, the image will make sure that real and Fourier space information about the image are always in sync. If, for example, the pixel sampling is changed while the current active domain is real space, the pixel sampling in Fourier space will be adjusted accordingly, and vice versa.
Creating and visualizing ImageHandles¶
As a first step, enter the following lines in the OpenStructure python console:
im=img.CreateImage(img.Size(200,200))
This will create an empty, 2D image, with a height and width of 200 pixels, whose origin (ie the pixel with the coordinates <0,0>) is in the topleft corner.
v=gui.CreateDataViewer(im)
A viewer window will pop up (see below), showing a white frame on a black background. The inner area of the white frame is the image, which is empty.
Reading and writing into an image¶
Data can be read and written from and into an image using the following commands:
# writes the real value 23.4 into pixel 10,10
im.SetReal(img.Point(10,10),23.4)
# reads the value in pixel 10,10
val=im.GetReal(img.Point(10,10))
The complex equivalents are also available
# writes the complex value value 2+3j into pixel 10,10
im.SetComplex(img.Point(10,10),2+3j)
# reads the value in pixel 10,10
val=im.GetComplex(img.Point(10,10))
The image knows in which domain it is, and will adjust the type of data being
written accordingly. For example, if one writes a complex value in a
SPATIAL
image, the value will be automatically converted to a real one by
taking the amplitude of the complex number. On the other hand, if one writes a
real value in a FREQUENCY
image, the value is automatically
converted to complex by setting the imaginary part to 0.
Image properties¶
The data domain¶
The data domain of an image specifies wether the image contains data in the
spatial or frequency domain. A HALF_FREQUENCY
domain also exists,
representing centrosymmetric frequency data (such as the data coming from the
Fourier transform of an image from the real spatial domain)

SPATIAL
¶ Realvalued spatial images

COMPLEX_SPATIAL
¶ Complexvalued spatial images, i.e. resulting from a Fourier transform of the
FREQUENCY
domain.

FREQUENCY
¶ Complex frequeny domain.

HALF_FREQUENCY
¶ Centrosymmetric frequency images
The spatial origin¶
The spatial origin of an image is the first pixel of its extent. Specifically, this is the top left pixel for 2D images and the topfrontleft corner for 3D images.
The absolute origin¶
The absolute origin of an image describes the coordinates, in the absolute reference system used by OpenStructure, of the pixel in with all indexes equal to 0. Please note that the pixel does not necessarily need to belong to the extent of the image.
Pixel sampling¶
The pixel sampling property of an image describes the size of its pixels. For
the same image, the size of pixels in the SPATIAL
and in the
FREQUENCY
The data domain are obviously interdependent.
OpenStructure takes care of the transformation and allows access to both pixel
sampling irrespective of the current image domain.
The ImageHandle class¶
The public interface of the ImageHandle class provides many ways to manipulate image properties. What follows is a brief description of the most important methods and attributes of the ImageHandle class.

class
ImageHandle
¶ 

type
¶ The DataType of an image represents the nature of the data it contains. An image can contain :obj`REAL` or
COMPLEX
values.

absolute_origin
¶ The absolute origin of an image describes the coordinates, in the absolute reference system used by OpenStructure, of the pixel in with all indexes equal to 0. Please note that the pixel does not necessarily need to belong to the extent of the image. Readwrite.
Type: Vec3

spatial_origin
¶ The spatial origin of an image is the first pixel of its extent. Specifically, this is the top left pixel for 2D images and the topfrontleft corner for 3Dimages.
Type: Point

domain
¶ The current domain of the image. See The data domain. Readonly.

Apply
(algorithm)¶ Applies an algorithm on an image and returns a new ImageHandle containing the modified image. See img.alg  Image Processing Algorithms
Parameters: algorithm (Instance of an algorithm class  See img.alg  Image Processing Algorithms.) – algorithm Return type: ImageHandle

ApplyIP
(algorithm)¶ Applies an algorithm on an image, overwriting the current content. See :doc:../alg/alg`
Parameters: algorithm (Instance of an algorithm class  See: doc:../alg/alg.) – algorithm

CenterSpatialOrigin
()¶ Sets the The spatial origin of an image in such a way that the central pixel has all 0 indexes, e.g. (0,0) or (0,0,0) for 3d images.

CoordToIndex
(coord)¶ Returns the indexes of an image corresponding to the specified absolute coordinates. (See The absolute origin). A given set of absolute coordinates will almost never fall exactly at the center of a pixel, so this method return fractional indexes.
Parameters: coord ( Vec3
) – Absolute coordinatesReturn type: Vec3

Copy
()¶ Creates a and returns a copy of the ImageHandle. The new handle does not point to the same underlying data as the old one, but to a complete and separate copy of the original data.
Return type: ImageHandle

Extract
(extent)¶ Creates and returns a new image that contains a copy of a portion of the original image. The extracted image keeps the same The data domain of the original image, but extractions from images in the ‘FREQUENCY’ or ‘HALF FREQUENCY’ domains result in
COMPLEX ` :obj:`SPATIAL
images. This transformation is necessary, since the there is no guarantee that the extractedFREQUENCY
subimage is centered around the origin and hence backtransformable toSPATIAL
.Parameters: extent ( Extent
) – Portion of the image to extractReturn type: ImageHandle

FractionalIndexToCoord
(frac_pixel)¶ Same as
IndexToCoord()
, but introduces subpixel precision by accepting fractional numbers for pixel indexes.Parameters: frac_pixel ( Vec3
) – Fractional pixel indexesReturn type: Vec3

GetAbsoluteOrigin
()¶ Returns the The absolute origin of an image
Return type: Vec3

GetComplex
(pixel)¶ Returns the complex value of the specified image pixel. If the image holds data of the ‘REAL’ The data domain, the method return s complex value with the pixel content as real part and a null imaginary part.
Parameters: pixel ( Point
) – Image pixelReturn type: complex

GetFrequencySampling
()¶ Returns the Pixel sampling of the image in the
FREQUENCY
The data domainReturn type: Vec3

GetIntpolComplex
(frac_pixel)¶ Returns the interpolated complex value of the virtual pixel corresponding to the specified fractional indexes. This is computed by calculating a weighted vector sum of the values of the surrounding pixels. If the image holds data of the ‘REAL’ The data domain, the method computes the interpolated value using bilinear interpolation (trilinear for 3D images), then returns a complex value with the interpolated value as real part and a null imaginary part.
Parameters: frac_pixel ( Vec3
) – Fractional pixel indexesReturn type: complex

GetIntpolReal
(frac_pixel)¶ Returns the interpolated value of the virtual pixel corresponding to the specified fractional indexes. This is computed by using bilinear interpolation (trilinear for 3D images). If the image holds data of the
COMPLEX ` :ref:`datadomain
, the method computes the interpolated value as a weighted vector sum of the values of the surrounding pixels, then returns the amplitude of the interpolated value.Parameters: frac_pixel ( Vec3
) – Fractional pixel indexesReturn type: float

GetPixelSampling
()¶ Returns the Pixel sampling of the image in the current The data domain.
Return type: Vec3

GetReal
(pixel)¶ Returns the value of the specified image pixel. If the image holds data of the
COMPLEX ` :ref:`datadomain
, the method return the amplitude of the pixel content.Parameters: pixel ( Point
) – Image pixelReturn type: float

GetSpatialOrigin
()¶ Returns the The spatial origin of the image.
Return type: Point

GetSpatialSampling
()¶ Return the Pixel sampling of the image in the
SPATIAL
The data domain.Return type: Vec3

GetType
()¶ Returns the The data domain of the image (
REAL
orCOMPLEX
)Return type: DataType ???????????

IndexToCoord
(pixel)¶ Returns the absolute coordinates (See The absolute origin) corresponding to the pixel with the specified indexes. Please note this method always returns the coordinates corresponding to the center of the pixel. When subpixel precision is needed, the method
FractionalIndexToCoord()
can be used.Parameters: pixel ( Point
) –Return type: Vec3

IsFrequency
()¶ Returns true if the The data domain of the image is FREQUENCY or HALFFREQUENCY
Return type: bool

IsSpatial
()¶ Returns true if the The data domain of the image is
SPATIAL
.Return type: bool

IsValid
()¶ Returns true, when the image handle is valid, false if not. It is an error to call any method on the image handle other than IsValid when this method returns false.
Return type: bool

Paste
(source_image)¶ Copies the content of a different image into the current one, overwriting preexisting data . The values of pixels with given indexes in the source image are copied into pixels with the same indexes in the target image. If the two images have different extents (see
Extent
), pixels that do not exist in both are ignored. Please notice that this method only copies the pixel content: all other properties of the image are left untouched.Parameters: source_image ( ImageHandle
) – Source image that gets pasted into the current one

SetAbsoluteOrigin
(coord)¶ Sets the The absolute origin of the image to the specified coordinates
Parameters: coord ( Vec3
) – Absolute coordinates

SetComplex
(pixel, value)¶ Sets the content of the specified pixel to the provided value. If the image holds data of the ‘REAL’ The data domain, the method sets the pixel to the amplitude of the provided. value.
Parameters:  pixel (
Point
) – Image pixel  value (complex) – Value
 pixel (

SetPixelSampling
(sampling)¶ Sets the Pixel sampling of the image to the provided values in the current The data domain.
Parameters: sampling ( Vec3
) – Size of a pixel in x,y and z direction respectively

SetReal
(pixel, value)¶ Sets the content of the specified pixel to the provided value. If the image holds data of the
COMPLEX
The data domain, the method sets the pixel to a value has a real part equal to the provided value and a null complex part.Parameters:  pixel (
Point
) – Image pixel  value (float) – Value
 pixel (

SetSpatialOrigin
(pixel_indexes)¶ Sets the The spatial origin of the image to the provided indexes.
Parameters: pixel_indexes ( Point
) – Indexes of the first pixel of the imageReturn type: None

SetSpatialSampling
(sampl)¶ Sets the Pixel sampling if the image to the provided values in the spatial The data domain
Parameters: sampl ( Vec3
) – Size of a pixel in x,y and z direction respectively
