Introduction to the img Module

For the course of this tutorial, we assume that you have DNG up and running.

Loading Images and Density Maps

OpenStructure features an img module that is dedicated to the manipulation of images/density maps. The images or density maps can either be one-, two- or three-dimensional. The most common formats used in X-ray/ electron crystallography and atomic force microscopy are supported in addition to several general purpose image formats. See supported file formats for details. The img module was originally developed as part of the Image Processing Library & Toolbox IPLT. More documentation and examples can also be found on the IPLT website <>.

To load a density map, type

map = io.LoadImage('/path/to/examples/code_fragments/map/')

This will load the fragment density map from the specified file ‘’ and store the result in map.

Now let’s inspect what we just loaded:

print(map.GetPixelSampling(), map.GetSize())

We can see that the sampling is set to 1.0 Angstrom in all three dimensions. The loaded map is an instance of ImageHandle, a class to represent images in one, two and three dimensions.

Manipulating Images and Density Maps

The algorithms used for manipulation of an image are found in the img.alg module. Therefore before using an algorithm we first have to import the img.alg module.

from ost.img import alg

The img.alg module provides a wide range of algorithms to manipulate image data. Here for example we use a LowPassFilter to restrict the resolution of the density map to frequencies lower than a certain threshold.

map_filtered = map.Apply(alg.LowPassFilter(3.0))

The filtered map is stored in a new variable called map_filtered. A complete list of algorithms is available on the img.alg - Image Processing Algorithms page.

Displaying Images and Density Maps

Now that we have a filtered map it’s time to have a look at it. There are fundamentally two ways to visualize 3-dimensional density maps. One is by drawing isocontour surfaces. These are conceptually similar to contour lines used in cartography: every point on an isosurface has the same density value. Isosurfaces are easy to create in OpenStructure:

go = gfx.MapIso("filtered", map_filtered,0.5)

The other way to visualize a 3-dimensional map is by showing one 2-dimensional density slice at a time, allowing the user to move through the slices. In OpenStructure this is achieved using a DataViewer). A DataViewer showing the filtered map is created using the following command:


This command displays a panel showing one slice of the density map lying on a particular (x,y) plane in the coordinate reference system. The z and x keys can be used to move to slices lying at a lower or higher coordinate along the z axis, allowing the examination of the full 3-dimensional volume.

A more detailed explanation of the img module can be found in the tutorial section for img.

Continue with part three of the tutorial.


Enter search terms or a module, class or function name.


Documentation is available for the following OpenStructure versions:

dev / (Currently viewing 2.7) / 2.6 / 2.5 / 2.4 / 2.3.1 / 2.3 / 2.2 / 2.1 / 2.0 / 1.9 / 1.8 / 1.7.1 / 1.7 / 1.6 / 1.5 / 1.4 / 1.3 / 1.2 / 1.11 / 1.10 / 1.1

This documentation is still under heavy development!
If something is missing or if you need the C++ API description in doxygen style, check our old documentation for further information.