Back to index

radiance  4R0+20100331
tonemap.h
Go to the documentation of this file.
00001 /* RCSid $Id: tonemap.h,v 3.23 2008/05/31 19:38:36 greg Exp $ */
00002 /*
00003  * Header file for tone mapping functions.
00004  *
00005  * Include after "color.h"
00006  */
00007 #ifndef _RAD_TONEMAP_H_
00008 #define _RAD_TONEMAP_H_
00009 
00010 #include      "tiff.h"      /* needed for int32, etc. */
00011 
00012 #ifdef __cplusplus
00013 extern "C" {
00014 #endif
00015 
00016 /****    Argument Macros    ****/
00017                             /* flags of what to do */
00018 #define       TM_F_HCONTR   01            /* human contrast sensitivity */
00019 #define       TM_F_MESOPIC  02            /* mesopic color sensitivity */
00020 #define       TM_F_LINEAR   04            /* linear brightness mapping */
00021 #define       TM_F_ACUITY   010           /* acuity adjustment */
00022 #define       TM_F_VEIL     020           /* veiling glare */
00023 #define       TM_F_CWEIGHT  040           /* center weighting */
00024 #define       TM_F_FOVEAL   0100          /* use foveal sample size */
00025 #define       TM_F_BW              0200          /* luminance only */
00026 #define       TM_F_NOSTDERR 0400          /* don't report errors to stderr */
00027                             /* combined modes */
00028 #define       TM_F_CAMERA   0
00029 #define       TM_F_HUMAN    (TM_F_HCONTR|TM_F_MESOPIC|TM_F_VEIL|\
00030                             TM_F_ACUITY|TM_F_FOVEAL)
00031 #define       TM_F_UNIMPL   (TM_F_CWEIGHT|TM_F_VEIL|TM_F_ACUITY|TM_F_FOVEAL)
00032 
00033                             /* special pointer values */
00034 #define       TM_XYZPRIM    (RGBPRIMP)NULL       /* indicate XYZ primaries (Note 1) */
00035 #define       TM_NOCHROM    (BYTE *)NULL  /* indicate no chrominance */
00036 #define       TM_NOCHROMP   (BYTE **)NULL /* indicate no chrominances */
00037 #define       TM_GETFILE    (FILE *)NULL  /* indicate file must be opened */
00038 
00039 
00040 /****    Error Return Values    ****/
00041 
00042 #define TM_E_OK             0             /* normal return status */
00043 #define       TM_E_NOMEM    1             /* out of memory */
00044 #define       TM_E_ILLEGAL  2             /* illegal argument value */
00045 #define       TM_E_TMINVAL  3             /* no valid tone mapping */
00046 #define       TM_E_TMFAIL   4             /* cannot compute tone mapping */
00047 #define       TM_E_BADFILE  5             /* cannot open or understand file */
00048 #define TM_E_CODERR1 6             /* code consistency error 1 */
00049 #define TM_E_CODERR2 7             /* code consistency error 2 */
00050 
00051 
00052 /****    Conversion Constants and Table Sizes    ****/
00053 
00054 #define       TM_BRTSCALE   128           /* brightness scale factor (integer) */
00055 
00056 #define TM_NOBRT     (-1<<15)      /* bogus brightness value */
00057 #define TM_NOLUM     (1e-17)              /* ridiculously small luminance */
00058 
00059 #define       TM_MAXPKG     8             /* maximum number of color formats */
00060 
00061 
00062 /****    Global Data Types and Structures    ****/
00063 
00064 #ifndef       MEM_PTR
00065 #define       MEM_PTR              void *
00066 #endif
00067 
00068 extern char   *tmErrorMessage[];   /* error messages */
00069 
00070 typedef short TMbright;            /* encoded luminance type */
00071 
00072                             /* basic tone mapping data structure */
00073 typedef struct {
00074        int           flags;        /* flags of what to do */
00075        RGBPRIMP      monpri;              /* monitor RGB primaries */
00076        double        mongam;              /* monitor gamma value (approx.) */
00077        COLOR         clf;          /* computed luminance coefficients */
00078        int           cdiv[3];      /* computed color divisors */
00079        RGBPRIMP      inppri;              /* current input primaries */
00080        double        inpsf;        /* current input scalefactor */
00081        MEM_PTR              inpdat;              /* current input client data */
00082        COLORMAT      cmat;         /* color conversion matrix */
00083        TMbright      hbrmin, hbrmax;      /* histogram brightness limits */  
00084        int           *histo;              /* input histogram */
00085        TMbright      mbrmin, mbrmax;      /* mapped brightness limits */
00086        unsigned short       *lumap;              /* computed luminance map */
00087        MEM_PTR              pd[TM_MAXPKG];       /* pointers to private data */
00088        int           lastError;    /* last error incurred */
00089        const char    *lastFunc;    /* error-generating function name */
00090 } TMstruct;
00091 
00092                             /* conversion package functions */
00093 struct tmPackage {
00094        MEM_PTR              (*Init)(TMstruct *tms);
00095        void          (*NewSpace)(TMstruct *tms);
00096        void          (*Free)(MEM_PTR pp);
00097 };
00098                             /* our list of conversion packages */
00099 extern struct tmPackage     *tmPkg[TM_MAXPKG];
00100 extern int    tmNumPkgs;    /* number of registered packages */
00101 
00102 
00103 /****    Useful Macros    ****/
00104 
00105                             /* compute luminance from encoded value */
00106 #define       tmLuminance(li)      exp((li)*(1./TM_BRTSCALE))
00107 
00108                             /* does tone mapping need color matrix? */
00109 #define tmNeedMatrix(t)     ((t)->monpri != (t)->inppri)
00110 
00111                             /* register a conversion package */
00112 #define tmRegPkg(pf) ( tmNumPkgs >= TM_MAXPKG ? -1 : \
00113                             (tmPkg[tmNumPkgs] = (pf), tmNumPkgs++) )
00114 
00115                             /* get the specific package's data */
00116 #define tmPkgData(t,i)      ((t)->pd[i]!=NULL ? (t)->pd[i] : (*tmPkg[i]->Init)(t))
00117 
00118 
00119 /****    Library Function Calls    ****/
00120 
00121 extern TMbright
00122 tmCvLuminance(double lum);
00123 /*
00124        Convert a single luminance value to an encoded brightness value.
00125  */
00126 
00127 extern int
00128 tmCvLums(TMbright *ls, float *scan, int len);
00129 /*
00130        Convert luminance values to encoded brightness values using lookup.
00131 
00132        ls     -      returned encoded luminance values.
00133        scan   -      input scanline.
00134        len    -      scanline length.
00135 
00136        returns       -      0 on success, TM_E_* on error.
00137  */
00138 
00139 extern TMstruct *
00140 tmInit(int flags, RGBPRIMP monpri, double gamval);
00141 /*
00142        Allocate and initialize new tone mapping.
00143 
00144        flags  -      TM_F_* flags indicating what is to be done.
00145        monpri -      display monitor primaries (Note 1).
00146        gamval -      display gamma response (can be approximate).
00147 
00148        returns       -      new tone-mapping pointer, or NULL if no memory.
00149 */
00150 
00151 extern int
00152 tmSetSpace(TMstruct *tms, RGBPRIMP pri, double sf, MEM_PTR dat);
00153 /*
00154        Set color primaries and scale factor for incoming scanlines.
00155 
00156        tms    -      tone mapping structure pointer.
00157        pri    -      RGB color input primaries (Note 1).
00158        sf     -      scale factor to get to luminance in cd/m^2.
00159        dat    -      application-specific data (NULL if not needed)
00160 
00161        returns       -      0 on success, TM_E_* code on failure.
00162 */
00163 
00164 extern void
00165 tmClearHisto(TMstruct *tms);
00166 /*
00167        Clear histogram for current tone mapping.
00168 
00169        tms    -      tone mapping structure pointer.
00170 */
00171 
00172 extern int
00173 tmAddHisto(TMstruct *tms, TMbright *ls, int len, int wt);
00174 /*
00175        Add brightness values to current histogram.
00176 
00177        tms    -      tone mapping structure pointer.
00178        ls     -      encoded luminance values.
00179        len    -      number of luminance values.
00180        wt     -      integer weight to use for each value (usually 1 or -1).
00181 
00182        returns       -      0 on success, TM_E_* on error.
00183 */
00184 
00185 extern int
00186 tmFixedMapping(TMstruct *tms, double expmult, double gamval);
00187 /*
00188        Assign a fixed, linear tone-mapping using the given multiplier,
00189        which is the ratio of maximum output to uncalibrated input.
00190        This mapping will be used in subsequent calls to tmMapPixels()
00191        until a new tone mapping is computed.
00192        Only the min. and max. values are used from the histogram.
00193        
00194        tms    -      tone mapping structure pointer.
00195        expmult       -      the fixed exposure multiplier to use.
00196        gamval -      display gamma response (0. for default).
00197 
00198        returns -     0 on success, TM_E_* on error.
00199 */
00200 
00201 extern int
00202 tmComputeMapping(TMstruct *tms, double gamval, double Lddyn, double Ldmax);
00203 /*
00204        Compute tone mapping function from the current histogram.
00205        This mapping will be used in subsequent calls to tmMapPixels()
00206        until a new tone mapping is computed.
00207        I.e., calls to tmAddHisto() have no immediate effect.
00208 
00209        tms    -      tone mapping structure pointer.
00210        gamval -      display gamma response (0. for default).
00211        Lddyn  -      the display's dynamic range (0. for default).
00212        Ldmax  -      maximum display luminance in cd/m^2 (0. for default).
00213 
00214        returns       -      0 on success, TM_E_* on failure.
00215 */
00216 
00217 extern int
00218 tmMapPixels(TMstruct *tms, BYTE *ps, TMbright *ls, BYTE *cs, int len);
00219 /*
00220        Apply tone mapping function to pixel values.
00221 
00222        tms    -      tone mapping structure pointer.
00223        ps     -      returned pixel values (Note 2).
00224        ls     -      encoded luminance values.
00225        cs     -      encoded chrominance values (Note 2).
00226        len    -      number of pixels.
00227 
00228        returns       -      0 on success, TM_E_* on failure.
00229 */
00230 
00231 extern TMstruct *
00232 tmDup(TMstruct *orig);
00233 /*
00234        Duplicate the given tone mapping into a new struct.
00235 
00236        orig   -      tone mapping structure to duplicate.
00237 
00238        returns       -      pointer to new struct, or NULL on error.
00239 */
00240 
00241 extern void
00242 tmDone(TMstruct *tms);
00243 /*
00244        Free data associated with the given tone mapping structure.
00245 
00246        tms    -      tone mapping structure to free.
00247 */
00248 
00249 extern int
00250 tmCvGrays(TMstruct *tms, TMbright *ls, float *scan, int len);
00251 /*
00252        Convert gray float scanline to encoded luminance.
00253 
00254        tms    -      tone mapping structure pointer.
00255        ls     -      returned encoded luminance values.
00256        scan   -      input scanline.
00257        len    -      scanline length.
00258 
00259        returns       -      0 on success, TM_E_* on error.
00260 */
00261 
00262 extern int
00263 tmCvColors(TMstruct *tms, TMbright *ls, BYTE *cs, COLOR *scan, int len);
00264 /*
00265        Convert RGB/XYZ float scanline to encoded luminance and chrominance.
00266 
00267        tms    -      tone mapping structure pointer.
00268        ls     -      returned encoded luminance values.
00269        cs     -      returned encoded chrominance values (Note 2).
00270        scan   -      input scanline.
00271        len    -      scanline length.
00272 
00273        returns       -      0 on success, TM_E_* on error.
00274 */
00275 
00276 extern int
00277 tmCvColrs(TMstruct *tms, TMbright *ls, BYTE *cs, COLR *scan, int len);
00278 /*
00279        Convert RGBE/XYZE scanline to encoded luminance and chrominance.
00280 
00281        tms    -      tone mapping structure pointer.
00282        ls     -      returned encoded luminance values.
00283        cs     -      returned encoded chrominance values (Note 2).
00284        scan   -      input scanline.
00285        len    -      scanline length.
00286 
00287        returns       -      0 on success, TM_E_* on error.
00288 */
00289 
00290 extern int
00291 tmLoadPicture(TMstruct *tms, TMbright **lpp, BYTE **cpp, int *xp, int *yp,
00292               char *fname, FILE *fp);
00293 /*
00294        Load Radiance picture and convert to tone mapping representation.
00295        Memory for the luminance and chroma arrays is allocated using
00296        malloc(3), and should be freed with free(3) when no longer needed.
00297        Calls tmSetSpace() to calibrate input color space.
00298 
00299        tms    -      tone mapping structure pointer.
00300        lpp    -      returned array of encoded luminances, picture ordering.
00301        cpp    -      returned array of encoded chrominances (Note 2).
00302        xp, yp -      returned picture dimensions.
00303        fname  -      picture file name.
00304        fp     -      pointer to open file (Note 3).
00305 
00306        returns       -      0 on success, TM_E_* on failure.
00307 */
00308 
00309 extern int
00310 tmMapPicture(BYTE **psp, int *xp, int *yp, int flags,
00311               RGBPRIMP monpri, double gamval, double Lddyn, double Ldmax,
00312               char *fname, FILE *fp);
00313 /*
00314        Load and apply tone mapping to Radiance picture.
00315        If fp is TM_GETFILE and (flags&TM_F_UNIMPL)!=0, tmMapPicture()
00316        calls pcond to perform the actual conversion, which takes
00317        longer but gives access to all the TM_F_* features.
00318        Memory for the final pixel array is allocated using malloc(3),
00319        and should be freed with free(3) when it is no longer needed.
00320 
00321        psp    -      returned array of tone mapped pixels, picture ordering.
00322        xp, yp -      returned picture dimensions.
00323        flags  -      TM_F_* flags indicating what is to be done.
00324        monpri -      display monitor primaries (Note 1).
00325        gamval -      display gamma response.
00326        Lddyn  -      the display's dynamic range (0. for default).
00327        Ldmax  -      maximum display luminance in cd/m^2 (0. for default).
00328        fname  -      picture file name.
00329        fp     -      pointer to open file (Note 3).
00330 
00331        returns       -      0 on success, TM_E_* on failure.
00332 */
00333 
00334 extern int
00335 tmCvRGB48(TMstruct *tms, TMbright *ls, BYTE *cs, uint16 (*scan)[3],
00336               int len, double gv);
00337 /*
00338        Convert 48-bit RGB scanline to encoded luminance and chrominance.
00339 
00340        tms    -      tone mapping structure pointer.
00341        ls     -      returned encoded luminance values.
00342        cs     -      returned encoded chrominance values (Note 2).
00343        scan   -      input scanline.
00344        len    -      scanline length.
00345        gv     -      input gamma value.
00346 
00347        returns       -      0 on success, TM_E_* on error.
00348 */
00349 
00350 extern int
00351 tmCvGray16(TMstruct *tms, TMbright *ls, uint16 *scan, int len, double gv);
00352 /*
00353        Convert 16-bit gray scanline to encoded luminance.
00354 
00355        tms    -      tone mapping structure pointer.
00356        ls     -      returned encoded luminance values.
00357        scan   -      input scanline.
00358        len    -      scanline length.
00359        gv     -      input gamma value.
00360 
00361        returns       -      0 on success, TM_E_* on error.
00362 */
00363 
00364 /****    Notes    ****/
00365 /*
00366        General:
00367 
00368        The usual sequence after calling tmInit() is to convert some
00369        pixel values to chroma and luminance encodings, which can
00370        be passed to tmAddHisto() to put into the tone mapping histogram.
00371        This histogram is then used along with the display parameters
00372        by tmComputeMapping() to compute the luminance mapping function.
00373        (Colors are tone-mapped as they are converted if TM_F_MESOPIC
00374        is set.)  The encoded chroma and luminance values may then be
00375        passed to tmMapPixels() to apply the computed tone mapping in
00376        a second pass.
00377 
00378        Especially for RGBE colors in the same color space as the
00379        target display, the conversion to chroma and luminance values
00380        is fast enough that it may be recomputed on the second pass
00381        if memory is at a premium.  (Since the chroma values are only
00382        used during final mapping, setting the cs parameter to TM_NOCHROM
00383        on the first pass will save time.)  Another memory saving option
00384        if third and subsequent passes are not needed is to use the
00385        same array to store the mapped pixels as used to store
00386        the encoded chroma values.  This way, only two extra bytes
00387        for storing encoded luminances are required per pixel.  This
00388        is the method employed by tmMapPicture(), for example.
00389 */
00390 /*
00391        Note 1:
00392 
00393        All RGBPRIMP values should be pointers to static structures.
00394        I.e., the same pointer should be used for the same primaries,
00395        and those primaries should not change from one call to the next.
00396        This is because the routines use the pointer value to identify
00397        computed conversion matrices, so the matrices do not have to be
00398        rebuilt each time.  If you are using the standard primaries,
00399        use the standard primary pointer, stdprims.
00400 
00401        To indicate a set of input primaries are actually CIE XYZ,
00402        the TM_XYZPRIM macro may be passed.  If the input primaries
00403        are unknown, it is wisest to pass tmTop->monpri to tmSetSpace().
00404        By default, the input primaries equal the monitor primaries
00405        and the scalefactor is set to WHTEFFICACY in tmInit().
00406 */
00407 /*
00408        Note 2:
00409 
00410        Chrominance is optional in most of these routines, whether
00411        TM_F_BW is set or not.  Passing a value of TM_NOCHROM (or
00412        TM_NOCHROMP for picture reading) indicates that returned
00413        color values are not desired.
00414        
00415        If TM_NOCHROM is passed to a mapping routine expecting chroma
00416        input, it will do without it and return luminance channel
00417        rather than RGB pixel values.  Otherwise, the array for
00418        returned pixel values may be the same array used to pass
00419        encoded chrominances if no other mappings are desired.
00420 */
00421 /*
00422        Note 3:
00423 
00424        Picture files may either be opened by the calling routine or by
00425        the library function.  If opened by the calling routine, the
00426        pointer to the stream is passed, which may be a pipe or other
00427        non-seekable input as it is only read once.  It must be
00428        positioned at the beginning when the function is called, and it
00429        will be positioned at the end on return.  It will not be closed.
00430        If the passed stream pointer is TM_GETFILE, then the library
00431        function will open the file, read its contents and close it
00432        before returning, whether or not an error was encountered.
00433 */
00434 
00435 #ifdef __cplusplus
00436 }
00437 #endif
00438 #endif /* _RAD_TONEMAP_H_ */
00439