# Image Class Reference

Related Scripting Object: Image

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

`#include <xsi_image.h>`

Inheritance diagram for Image:

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

## Detailed 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"

## 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:

- xsi_image.h