Image Class Reference
 
 
 
Image Class Reference

#include <xsi_image.h>


Class Description

This class provides read-access to the representation of an image in memory.

For the vast majority of image files XSI will represent the data in memory as uncompressed 8-bit RGBA. This is true even if the original file has no alpha information. However, high quality 16-bit and floating point images can also be read via Image::GetPixelArray. You can determine what format the image data contains by means of Image::GetNumChannels and Image::GetChannelSize.

See also:
ImageClip2::GetImage
Since:
4.0
Example:
Demonstrates how to create an image clip and access information about its underlying image source.
                using namespace XSI;
                Application app ;

                // Create an image clip based on one of the
                // image files from the XSI installation
                CString strImagePath ;
                strImagePath = app.GetInstallationPath( siFactoryPath );
                strImagePath += L"/Data/XSI_SAMPLES/Pictures/upper_eyelash.jpg" ;

                CValueArray args(2);
                CValue retVal;
                args[0] = strImagePath ;
                args[1] = L"MySmallClip" ;

                app.ExecuteCommand( L"CreateImageClip", args, retVal ) ;

                ImageClip2 newClip = retVal ;
                Image myImage = newClip.GetImage() ;

                app.LogMessage( L"Image has resolution " + CValue( myImage.GetResX() ).GetAsText() +
                                        L" by " + CValue( myImage.GetResY() ).GetAsText() ) ;

                app.LogMessage( L"Image has " + CValue( myImage.GetNumChannels() ).GetAsText() +
                                        L" channels and " + CValue( myImage.GetChannelSize() ).GetAsText() +
                                        L" bytes per channel" ) ;

                app.LogMessage( L"Total size of the uncompressed image data is "
                                        + CValue( myImage.GetPixelArraySize() / 1024l ).GetAsText()
                                        + L" kb" ) ;

                // Get the pixel value at (45, 25)
                unsigned char aColor[4] ;
                myImage.GetPixelValue( 45.0, 25.0, aColor[0], aColor[1], aColor[2], aColor[3] ) ;

                // Alternatively we can use the CColor object, which holds the color as
                // normalized doubles
                CColor myColor ;
                myImage.GetPixelValue( 45.0, 25.0, myColor ) ;

                // Expect results of running this example:
                // INFO : "Image has resolution 875 by 300"
                // INFO : "Image has 4 channels and 1 bytes per channel"
                // INFO : "Total size of the uncompressed image data is 1025 kb"
Inheritance diagram for Image:
CBase

List of all members.

Public Member Functions

  Image ()
  ~Image ()
  Image (const CRef &in_ref)
  Image (const Image &in_obj)
bool  IsA (siClassID in_ClassID) const
siClassID  GetClassID () const
Image operator= (const Image &in_obj)
Image operator= (const CRef &in_ref)
CStatus  GetPixelValue (float in_X, float in_Y, CColor &out_Pixels) const
CStatus  GetPixelValue (float in_X, float in_Y, unsigned char &out_R, unsigned char &out_G, unsigned char &out_B, unsigned char &out_A) const
LONG  GetResX () const
LONG  GetResY () const
LONG  GetNumChannels () const
LONG  GetChannelSize () const
const void *  GetPixelArray () const
LONG  GetPixelArraySize () const

Constructor & Destructor Documentation

Image ( )

Default constructor.

~Image ( )

Default destructor.

Image ( const CRef in_ref )

Constructor.

Parameters:
in_ref constant reference object.
Image ( const Image in_obj )

Copy constructor.

Parameters:
in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID  in_ClassID ) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:
in_ClassID class type.
Returns:
true if the class is compatible, false otherwise.

Reimplemented from CBase.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:
The class type.

Implements CBase.

Image& operator= ( const Image in_obj )

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:
in_obj constant class object.
Returns:
The new Image object.
Image& operator= ( const CRef in_ref )

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:
in_ref constant class object.
Returns:
The new Image object.
CStatus GetPixelValue ( float  in_X,
float  in_Y,
CColor out_Pixels 
) const

Reads the color value at a specified pixel value in the image. When in_X or in_Y are not whole numbers Bilinear interpolation is used to determine a subpixel value. The bottom left of the image is considered pixel 0,0.

Parameters:
in_X X coordinate on the image.
in_Y Y coordinate on the image.
Return values:
out_Pixels The color of the image at the given coordinate
CStatus GetPixelValue ( float  in_X,
float  in_Y,
unsigned char &  out_R,
unsigned char &  out_G,
unsigned char &  out_B,
unsigned char &  out_A 
) const

Alternative signature of GetPixelValue which retrieves the color of the pixel as 4 RGBA bytes.

Currently this function only works for 8-bit RGBA images. For other image formats it is possible to read pixel values by calling Image::GetPixelArray.

Parameters:
in_X X coordinate on the image.
in_Y Y coordinate on the image.
Return values:
out_R The red component value of the color of the image at the given coordinate
out_G The green component value of the color of the image at the given coordinate
out_B The blue component value of the color of the image at the given coordinate
out_A The alpha component value of the color of the image at the given coordinate
LONG GetResX ( ) const

Returns the resolution, in pixels, of the horizontal dimension.

LONG GetResY ( ) const

Returns the resolution, in pixels, of the vertical dimension.

LONG GetNumChannels ( ) const

Returns the number of channels per pixel. Normally this returns 4, representing RGBA. XSI will often represent an image in memory with 4 channels even if the underlying file format has no alpha information.

LONG GetChannelSize ( ) const

Returns the number of bytes per channel. Normally this returns 1, but 16-bit images will return 2 and 32-bit float images will return 4.

const void* GetPixelArray ( ) const

Provides low level access to the image data. The returned buffer should not be modified and the pointer should not be cached outside the lifetime of the Image object. The data is formatted as an array of pixel color values, row by row.

You can find the exact format of each pixel by calling Image::GetNumChannels and Image::GetChannelSize. In the normal case, each pixel is represented by 4 bytes.

LONG GetPixelArraySize ( ) const

Returns the total size, in bytes, of the array returned by Image::GetPixelArray. It is expected that this is equal to the product of Image::GetResX, Image::GetResY, Image::GetNumChannels and Image::GetChannelSize.


The documentation for this class was generated from the following file: