Loading and Saving Raster Images

Table Of Contents

• Overview of Loading and Saving Raster Images
• Opening Image Files
• Data Organization
• Resolution
• Data Window
• Orientation and Flipping
• Color Correction
• Format Options
• HDK_Image_ApplyingOptions
• Options & Settings From Mantra
• HDK_Image_QueryingTheImage
• HDK_Image_ReadingScanlines
• HDK_Image_WritingScanlines
• HDK_Image_Closing
• HDK_Image_Installing
• HDK_Image_FAQ
• HDK_Image_IMG_Raster

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.

UT_PtrArray<PXL_Raster *> images;

IMG_File *file = IMG_File::open("Snail.pic");
if(file)
{
    bool success = file->readImages(images);
    file->close();
    delete file;

    if(success)
    {
        // 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.

Resolution

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