Radiance macbethcal program

MACBETHCAL(1)                                                    MACBETHCAL(1)

NAME

       macbethcal - compute color compensation based on measured Macbeth chart

SYNOPSIS

       macbethcal [ -d debug.hdr ][ -p xul yul xur  yur  xll  yll  xlr  ylr  ]
       scannedin.hdr [ calibout.cal ]
       macbethcal -c [ -d debug.hdr ] [ measured.xyY [ calibout.cal ] ]

DESCRIPTION

       Macbethcal  takes  a scanned image or measurement set of a Macbeth Col-
       orCheckerTM color rendition chart and computes a color mapping function
       suitable as input to pcomb(1).

       In  the first form, macbethcal takes a scanned image of a Macbeth chart
       that has been converted into a Radiance picture using  a  fixed  proce-
       dure.   When  used properly as input to pcomb, the computed calibration
       file will adjust the brightness and color of any similarly scanned  and
       converted image so as to best match the original.  If the lighting con-
       ditions are carefully controlled (as in the case of a flatbed scanner),
       it  is  even  possible  to get reliable reflectance values this way, at
       least within 10% or so.  The input picture  is  named  on  the  command
       line.  The output calibration file will be written to the standard out-
       put if no file name is given on the command line.

       In the second form, the input is from a file containing measured values
       for each Macbeth color.  This file must contain entries of the form:

       N    x    y    Y

       Where N is the number of the corresponding Macbeth color.  (See back of
       ColorChecker chart for color  names  and  indexing,  but  it  basically
       starts from the upper left with 1 and proceeds in English text order to
       the lower right, which is 24.)  The values x, y and Y are the 1931  CIE
       (x,y)  chromaticity  coordinates  followed  by  the  luminance for that
       color, which can be in any units.  If a white value is known (i.e. max-
       imum  output  level),  then  it  may  be  given as entry number 0.  The
       entries may be in any order, and comments may be included delimited  by
       a  pound  sign  ('#')  and continuing to the end of line.  It is recom-
       mended that measurements be done  for  all  24  colors,  but  the  only
       required  entries  are  the  6  neutral values on the bottom row of the
       chart.

       Computing a mapping from measured colors  is  usually  more  convenient
       when  calibrating  a particular output device.  This is accomplished by
       printing the picture macbeth_spec.hdr (which may be found in the  stan-
       dard  RADIANCE library directory in the lib subdirectory) and measuring
       the output with a chroma meter or spectrophotometer.

       For a scanned image, the locations of the 24  Macbeth  patches  in  the
       input picture must be known.  If the chart borders are not at the edges
       of the input picture, or the chart has been reversed or rotated  or  is
       uncentered  or at an oblique angle, then it is necessary to specify the
       pixel locations of the corners of the chart with the  -p  option.   The
       corner postions (x,y pixel addresses as given by the ximage(1) "p" com-
       mand) are ordered on the command line: upper-left, upper-right,  lower-
       left,  lower-right  (i.e.  English  text  ordering).  These coordinates
       should be the outside corner positions of the following patches:

       upper-left     = 1. dark skin
       upper-right    = 6. bluish green
       lower-left     = 19. white
       lower-right    = 24. black

       If the chart has been flipped or rotated, simply give the  pixel  posi-
       tions of the appropriate patch corners, wherever they are in the image.
       (Note: if the  Radiance  picture  has  been  flipped  or  rotated  with
       pflip(1) or protate(1), ximage will report the original pixel positions
       if the -c option was not used by the reorienting program(s).  This will
       be  wrong,  so  be sure to use the -c option.)  Macbethcal can handle a
       chart with any orientation or perspective warping if the corner coordi-
       nates are given correctly.  The debug picture output is the best way to
       check for consistency.  (See the -d option, below.)

       The -d option may be used to specify an additional output  file,  which
       will  be  a  picture comparing the scanned image processed according to
       the computed mapping against the standard Macbeth colors.  It is a good
       idea  to use the debug option to check that the color patches are being
       located correctly, and to see how well macbethcal does at matching col-
       ors.   The  center  of  each patch will show the target color; the left
       side of each patch will show the original color,  and  the  right  side
       will show the corrected value.  If the match works well, the debug pic-
       ture should have a sort of "notch on the  left"  look  in  each  patch.
       Macbeth colors that could not be matched because they were out of gamut
       on this device are indicated with  diagonal  lines  drawn  through  the
       associated target colors.

METHOD

       Macbethcal  computes  the color mapping in two stages.  The first stage
       uses the six neutral color patches at the bottom of the  Macbeth  chart
       to  compute  a piecewise linear approximation to the brightness mapping
       of each RGB primary.  The second stage looks at all the colors that are
       within  the  device's gamut to compute a least-sqaures fit for a linear
       color transformation from the measured space into the standard Radiance
       RGB space (as defined by the three primaries in src/common/color.h).

       Thanks  to  the  nature  of  inverse  mappings, this method should work
       either for converting scanned data to match the original, or  for  pre-
       conditioning  pictures to be sent to specific output devices.  In other
       words, the same calibration file works either  for  correcting  scanned
       images OR precorrecting images before printing.

       A  warning  is  printed if some unsaturated colors are determined to be
       out of gamut, as this may indicate a poor rendition or improper picture
       alignment.   The  debug picture will show which colors were excluded by
       drawing diagonal lines through their entries.

NOTE

       It is very important that the same settings be applied when scanning or
       printing other images to be calibrated with the computed file.  In par-
       ticular, all exposure adjustments should  be  fixed  manually,  and  no
       tweaking  of  the  settings  should  be  done along the way.  The final
       result will be best if the original scanned image is not  too  far  off
       from what it should be.  In the case of slide and negative scanners, it
       is best to apply the recommended calibration file for the type of  film
       used,  so  long as this calibration is fixed and not adjusted on a per-
       image basis.

CHART AVAILABILITY

       The Macbeth chart is available at most photographic supply  stores,  or
       may be ordered directly from Macbeth:

       Macbeth
       Munsell Color
       405 Little Britain Rd.
       New Windsor, NY  12553-6148
       tel. 1-800-622-2384 (USA)
       fax. 1-914-561-0267

       The chart sells for under $50 US at the time of this writing.

EXAMPLES

       To  compute  a  calibration  for  a  FunkyThing  scanner  and check the
       results:

         ra_tiff -r mbscan.tif mbscan.hdr
         macbethcal -d debug.hdr mbscan.hdr FunkyThing.cal
         ximage debug.hdr

       To apply this computed calibration to another scanned image:

         ra_tiff   -r   another.tif   |   pcomb   -f   FunkyThing.cal   -    >
         another_calib.hdr

       To compute a calibration file for the BigWhiz film recorder, after tak-
       ing measurements of a slide made from macbeth_spec.hdr:

         macbethcal -c macbeth_spec.xyY BigWhiz.cal

       To prepare a picture prior to output on the same film recorder:

         pcomb -f BigWhiz.cal standard.hdr > toprint.hdr

       To use pcond(1) to also adjust the image for human response:

         pcond -f BigWhiz.cal -h standard.hdr > toprint.hdr

AUTHOR

       Greg Ward
       Paul Heckbert supplied code for perspective projective mapping

SEE ALSO

       icalc(1), pcomb(1), pcond(1), pfilt(1), ximage(1)

RADIANCE                            1/16/97                      MACBETHCAL(1)