IMG/IMG_FileParms.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Mark Alexander
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        IMG_FileParm.h ( IMG Library, C++)
 *
 * COMMENTS:
 *      Parameter class for options to IMG_File::open() and IMG_File::create()
 */
#ifndef __IMG_FILE_PARMS_H__
#define __IMG_FILE_PARMS_H__

#include "IMG_API.h"

#include <SYS/SYS_Types.h>
#include <UT/UT_FilterType.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_IntArray.h>
#include <UT/UT_Rect.h>
#include <PXL/PXL_LumFuncs.h>

#include "IMG_FileTypes.h"

#if 0
class IMG_TileFileInfo;
#else
class IMG_TileOptions;
#endif


/// @brief  File options for manipulating image data on load or save.
/// This class allows you to modify the incoming or outgoing image data by
/// scaling, flipping, converting or cropping the data. It can be optionally
/// passed to IMG_File::open() or IMG_File::create()
class IMG_API IMG_FileParms
{
public:
    IMG_FileParms();

    /// This method turns off any option that would result in image
    /// translation.
    void readAsIs();

    // DATA ORGANIZATION ----------------------------------------------------

    /// @brief Convert to a different data type
    /// convert the image to this data type, if needed (default = use native)
    void   setDataType(IMG_DataType dt);
 
    /// @brief Convert to a different number of pixel components
    /// convert to a standard color model, if needed (RGB, RGBA, single).
    /// When moving from fewer components to more components, the
    /// data is either duplicated (1chan->RGB) or generated (RGB-RGBA, A=1). 
    void   setColorModel(IMG_ColorModel cm);

    /// @brief Interleaves or deinterleaves pixel data
    /// 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.
    /// Selects a plane by index. Indices are specified from 1 to # planes.
    void   selectPlanes(const UT_IntArray &planeindices);

    /// 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.
    /// Selects several planes by numeric pattern, ie. "1", "1 3 4", "[1-3] 5"
    void   selectPlanes(const char *pattern);

    /// 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.
    /// Selects serveral planes by name pattern, such as "C", "C A Pz" "P? C*"
    void   selectPlaneNames(const char *name);

    
    /// RESOLUTION -----------------------------------------------------------
    /// using these methods always scales. To crop, use the data window methods

    /// Scale the image to resolutuion (x,y). (0 = use orginal 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 ratio.
    void   powerTwoOnly();

    // DATA WINDOW ---------------------------------------------------------

    /// Normally, a data window is expanded or cropped to the image resolution.
    /// calling this will always read only the data window. 
    /// Used only for reading.
    void   setDataWindowOnly();

    /// read the image region in 'area' only (even if we need to crop or expand
    /// the image to fill it). Used only for reading.
    void   setWindow(const UT_DimRect &area);

    /// read the image region in 'area' in UV coords. Used only for reading.
    void   setWindow(float u1, float v1, float u2, float v2);

    // ORIENTATION ----------------------------------------------------------
    
    /// options for orienting and flipping the image. Default orienation is
    /// LEFT_FIRST, BOTTOM_FIRST. You can set each to 'none' if you don't care.
    void   orientImage(IMG_XOrientation x, IMG_YOrientation y);

    /// @brief Flip the image in either direction.
    /// flip the images in either direction. May cancel out any orientation
    /// flipping.
    /// @{
    void   flipImageVertical();
    void   flipImageHorizontal();
    /// @}

    /// rotate the image 90', flopping it on its side.
    void   flopImage();


    // COLOR CORRECTION -----------------------------------------------------
    
    /// @brief Color correct an image using a LUT
    /// apply a lookup table to the data, but only those planes that match the
    /// scope (ie, "C spec diff", "C*", "*beauty*")
    void   applyLUT(const char *lut, const char *plane_scope = "*");

    /// @brief Color correct an image using a gamma setting
    /// Apply gamma to the planes matching the scope (ie, "C spec diff", "C*",
    /// "*beauty*")
    void   applyGamma(fpreal gamma, const char *gamma_scope = "*");

    // FORMAT SPECIFIC OPTIONS ----------------------------------------------

    /// set an input/output tag option for the format.
    void        setOption(const char *option, const char *value);

    /// options are a list of argument pairs, such as "artist", "Tom Smith".
    /// The options list is terminated by a NULL.
    void        setOptions(const char **options);

    /// options are in a whitespace separated string "Artist 'Tom Jones'"
    void        setOptionsString(const char *option_pair_string);

    /// options are specified in the IMG_TileOptions structure
    void        setOptions(const IMG_TileOptions &info_with_options);

    /// @brief Enable the tile inteface for reading or writing
    /// If called, we're reading or writing tiles using IMG_File::readTile
    /// and IMG_File::writeTile. The scanline versions will not work.
    void   useTileInterface();

    /// If set, files will not report errors and subsequent scanlines
    /// will be returned as black. 
    void   continueOnError();

private:
    IMG_DataType     myDataType;
    IMG_ColorModel   myColorModel;
    IMG_XOrientation myOrientX;
    IMG_YOrientation myOrientY;
    int              myResX, myResY;
    fpreal           myScaleX, myScaleY;
    UT_FilterType    myFilterType;
    fpreal           myGamma;
    IMG_Interleave   myInterleaved;
    PXL_LumFunction  myLumFunc;

    unsigned       myFlipHorizontal : 1,
                   myFlipVertical : 1,
                   myFlopImage      : 1,
                   myReadDataWindowOnly :1,
                   myReadAreaFlag :1,
                   myReadUVAreaFlag : 1,
                   myUseTiles :1,
                   myUseLUT : 1,
                   myPowerTwoRes :1,
                   myResLimit:1,
                   myAlphaSplit : 1,
                   myContinueOnError : 1;
    
    UT_DimRect     myReadArea;
    fpreal         myReadUVArea[4];
    UT_String      myLUTFilename;
    UT_String      myLUTScope;
    UT_String      myGammaScope;
    UT_String      mySelectPlaneName;
    UT_IntArray    mySelectPlaneIndex;

    UT_StringArray myOptions;
    UT_StringArray myOptionValues;
    
    friend class IMG_File;
};



#endif

---