5.7. Images

Image node

The image node, SoImage SoImage SoImage , defines an image that will be rendered as a 2D screen-aligned image. The two-dimensional image is independent of camera rotation and does not scale in size depending on changes in distance from the camera.

SoImage SoImage SoImage has the following fields:

filename (SoSFString)

Specifies the file from which to read the image. See your release documentation for information on the file formats supported on your system. If the filename is not an absolute path name, the list of directories maintained by SoInput SoInput SoInput is searched. If the image file is not found in any of those directories, then the file is searched for relative to the directory from which the SoImage SoImage SoImage node was read. For example, if an SoImage SoImage SoImage node with a filename of “../tofu.rgb” is read from /usr/people/bob/models/food.iv, then /usr/people/bob/tofu.rgb will be read (assuming tofu.rgb isn’t found in the directories maintained by SoInput SoInput SoInput ).

image (SoSFImage)

Contains an in-memory representation of the image. It is either the contents of the file read from filename, an image read directly from an Inventor file, or an image set programmatically using the methods provided by SoSFImage SoSFImage SoSFImage . For more information about the storage of the image, read the paragraph the section called “Storing an Image (Advanced) of The Inventor Mentor.

horAlignment (SoSFEnum)

vertAlignment (SoSFEnum)

Horizontal and vertical alignment relative to the image origin.

width (SoSFInt32)

height (SoSFInt32)

Specifies the width and the height of the image in pixels in order to magnify or reduce it. If one these values is equal to -1, the original size (width or height) of the image is used. For instance if width = 256 and height = -1, and the original size is 128x128 pixels, the resulting size will be 256 for the width and 128 for the height.

The image origin is positioned at (0,0,0), transformed by the current geometric transformation. The image is drawn relative to the image origin, according to the specified vertical and horizontal alignment.

Furthermore, although texturing is ignored by the HardCopy extension, this node may be used for correct printing of scenes containing logos or images.

Example 5.12. An image using the SoImage node

This example displays an image using the SoImage SoImage SoImage node. The program source code is available in:



main(int argc, char **argv)
  // Initialize Inventor and Xt
  Widget myWindow = SoXt::init(argv[0]);
  SoSeparator *root = new SoSeparator;
  // Create the image node using
  // the file "./sillyFace.rgb"
  // as source.
  SoImage *image = new SoImage;
  image->filename = "sillyFace.rgb";
  // Create a viewer
  SoXtExaminerViewer *myViewer = new SoXtExaminerViewer(myWindow);
  // attach and show viewer
  // Loop forever
  return 0;
SoSeparator root = new SoSeparator();

// Create the image node using the file sillyFace.png as source.
SoImage Image = new SoImage();
string ImagePath = SbFileHelper.ExpandString(
Image.filename.Value = ImagePath;


// Create a viewer
SoWinExaminerViewer myViewer = new SoWinExaminerViewer(this, "", true, 

// attach and show viewer


Figure 5.34. Raster image classes

SoRasterImageRW SoRasterImageRW SoRasterImageRW allows you to read and write image buffers from/to a file. Subclasses are derived from this abstract class to support common graphic file formats such as BMP, DDS, GIF, JPEG2000, JPEG, PGX, PNG, PostScript, SGI (RGBA), RAS (Sun Raster), and TIFF. These classes dynamically load the format-specific libraries (libJPEG, libTIFF, libPNG...) only when needed.

Depending on the library capabilities, large images are written using tiles two different ways: WRITE_SCANLINES or WRITE_FULL_IMAGE. For the WRITE_SCANLINES formats, the image can be written incrementally, some number of scanlines at a time. Therefore it is only necessary to allocate enough memory for a single tile, which at most will be the size of the maximum OpenGL viewport (typically 2048x2048). If it is WRITE_FULL_IMAGE, the whole image buffer must be allocated and tiles are copied into it; this is less efficient and requires more memory.

All of the classes dealing with image I/O in Open Inventor and its modules use this set of classes to read or write graphics files (SoImage SoImage SoImage , SoTexture2 SoTexture2 SoTexture2 , SbTVizTexture , SoParticleAnimation SoParticleAnimation SoParticleAnimation ...) You can also create your own graphic file format import/export by deriving a subclass from SoRasterImageRW SoRasterImageRW SoRasterImageRW and implementing or overloading its methods:

SbBool open(SoRasterImageIO* rasterImageIO, OpenMode openMode)
void close()
SbBool write(SbRasterImage* rasterImage, unsigned int xPos=0, unsigned int yPos=0)
SbBool writeHeader(SbVec2s& size)
SbBool writeFooter()
SbBool read(SbRasterImage* rasterImage, SbBool infoOnly = FALSE)
boolean open(SoRasterImageIO rasterImageIO, OpenModes openMode)
void close()
boolean write(SbRasterImage rasterImage, int xPos, int yPos)
boolean writeHeader(SbVec2s size)
boolean writeHeader(SbVec2i32 size)
boolean writeFooter()
boolean read(SbRasterImage rasterImage, boolean infoOnly)

An example program in the distribution shows how to create your own graphics file reader/writer (PPM format). It can be found at: $OIVHOME/Inventor/examples/Features/RasterRW.