All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Loading and Saving Raster Images

Table Of Contents

Overview of Loading and Saving Raster Images

Images are loaded and saved by the IMG_File class, which provides a variety of features:

  • Interface to many image formats, including plugins
  • Scanline by scanline, tile-by-tile, or full image processing
  • Data translation (deinterleaving, bit depth changes, color model changes)
  • Image scaling and cropping
  • Color correction via LUTs and gamma
  • IO from filenames or streams

The easiest way to load an image file is to open() it, readImages() from it, and then close() the file.

IMG_File *file = IMG_File::open("Snail.pic");
bool success = file->readImages(images);
delete file;
// use rasters in images, and free them when you're done.

The following sections describe this process in more detail.

Opening Image Files

To open an image for reading, pass the filename to IMG_File::open(). You can also pass in an IMG_FileParms structure to tell the loader how to organize your data. By using the IMG_FileParms correctly, you may be able to avoid the need to post-process the scanline data. Not all the parameters are available for writing, since most of the data for the write is specified in the IMG_Stat. See the "Write Effect" section in each for what applies to writing and what is ignored.

IMG_FileParms allows you to do the following:

Data Organization

Raster depth conversion and RGB/RGBA conversions are common re-organizations. Now, you can also specify if you want the data interleaved (RGBRGBRGB) or non-interleaved (RRRGGGBBB) or as-is.

By default, the data is interleaved and left at the native raster depth and color model.

// convert the data type (default = use native)
void setDataType(IMG_DataType dt);
// convert to a standard color model (RGB, RGBA, single). Each plane
// will be this color model.
void setColorModel(IMG_ColorModel cm);
// Determines how to format the data.
// IMG_INTERLEAVE_AS_IS - leave it interleaved or non, as in the file.
// IMG_INTERLEAVED - always interleave (rgbrgbrgb). Default.
// IMG_NON_INTERLEAVED - always non-interleaved (rrrgggbbb)
void setInterleaved(IMG_Interleave i);
// If the color model is set to IMG_1CHAN, and the actual color model
// is RGB or higher, this method determines how to convert the vector
// into a scalar. By default, the luminance is taken.
void setLuminanceFunc(PXL_LumFunction f);
// If true, alpha will be read into its own plane, instead of an RGBA
// color plane. Color will be read as its own plane as well, RGB.
void readAlphaAsPlane();
// If demoting from a deep raster to an RGB(A) image, these methods
// allow you to specify the plane(s) to copy to RGB(A), by name or index.
// Indices are specified from 1 to #planes.
void selectPlane(const UT_IntArray &planeindices);
// Selects by numeric pattern, for example "1", "1 3 4", "[1-3] 2"
void selectPlane(const char *pattern);
// Selects by plane name pattern, such as "C", "C A Pz" "P? C*"
void selectPlaneName(const char *name);

Write Effect

These are the effects of the above IMG_FileParms methods when writing:

- setDataType() - write the data as type (if supported by format).
- setColorModel() - write the data in model model (if supported by format).
- setInterleaved() - specifies how we are passing the data - as interleaved or non-interleaved (default interleaved).
- setLuminanceFunc() - if demoting an RGB(A) plane to a single channel, specifies how to do it.
- all others - ignored for writing.


In addition to scaling to a given resolution, the new API also supports some more common scale operations. Most of these are mutually exclusive. To do cropping instead of scaling, see Data Window below.

By default, the native resolution is used.

// scale the image to resolution (x,y). (0 = use original dimension)
void scaleImageTo(int x, int y, UT_FilterType ft=UT_FILTER_BOX);
// scale the image by scaling factors (x,y).
void scaleImageBy(fpreal x, fpreal y, UT_FilterType ft=UT_FILTER_BOX);
// limit the image to a maximum resolution. Scale to this res, preserving
// the aspect ratio.
void limitImageRes(int x, int y, UT_FilterType ft=UT_FILTER_BOX);
// images must be read as powers of two. Does not preserve aspect.
void powerTwoOnly();

Write Effect

ignored for all.

Data Window

Data windows can be embedded in certain file formats, but you can also specify your own window (regardless of whether a data window exists in the file). When specifying a subregion to read, you will be reading that area, not the full image area.

By default, all file data windows are expanded to fill the entire image.

// normally, a data window is expanded or cropped to the image resolution.
// calling this will always read only the data window.
void setDataWindowOnly();
// read the image region in 'area' only (even if we need to crop or expand
// the image to fill it)
void setWindow(const UT_DimRect &area);
// fills the data outside the window with bgcol. If reading, this overrides
// any outside behavior embedded in the file.
void setWindowOutsideColor(fpreal bgcol[4]);
// fills the data outside the window by streaking the edges outward to
// fill the area.
void setWindowStreak();

Write Effect

ignored for all.

Orientation and Flipping

In addition to being able to flip a file vertically, the new API allows you to specify an orientation and then flip horizontally or vertically. You can also flop the image (rotate it 90'). The orientation and flip work together to avoid doubling flipping.

By default, the image is read so that the (0,0) pixel is in the bottom left corner of the image.

// options for orienting and flipping the image. Default orientation is
// LEFT_FIRST, BOTTOM_FIRST. You can set each to 'none' if you don't care.
void orientImage(IMG_XOrientation x, IMG_YOrientation y);
void flipImageVertical();
void flipImageHorizontal();
// rotate the image 90', flopping it on its side.
void flopImage();

Write Effect

Specifies how to flip the image when outputting. flopImage() ignored.

Color Correction

You can also specify color correction to be applied to the image before any of its data is converted (ie, if you're converting a FP image to an 8 bit texture, you can apply gamma and/or a LUT first, before quantization occurs).

By default, no color correction is performed.

// apply a lookup table to the data, but only those planes that match the
// scope.
void applyLUT(const char *lut, const char *plane_scope = "*");
// Apply gamma to the planes matching the scope.
void applyGamma(fpreal gamma, const char *gamma_scope = "*");

Write Effect

Applies a LUT and gamma to the output planes which match the scope.

Format Options

You can set format-specific options, like compression, through the IMG_FileParms::setOption() method. This is still relatively simplistic, as it takes a string for both option name and value. This may be upgraded later.

Reading or Writing Tiles

You can use a tile-based interface to IMG_File for writing data as well. Internally, this still uses scanlines. This is a convenience function for ease of data manipulation only.

// if set, we're reading or writing tiles with readTile() and writeTile()
// instead of readScanline() and writeScanline(). The area of each tile may
// vary per call, but no pixel may be written twice for the same plane.
void useTileInterface();

Options & Settings From Mantra

It's possible to extend SOHO to add image options the user can pass to the image format being rendered. If you examine $HH/soho/python