spectro/spotread
    Summary
    Use an instrument to read a single color value. This can be a useful
    diagnostic aid.
    
    [ A commercial tool that does much of what spotread does and more,
    is the ArgyllPRO ColorMeter.
    ]
    Usage Summary
    spotread [-options]
        [logfile]
       -v             
              Verbose mode
       -s             
              Print spectrum for each reading.
     -S
                    
              Plot the spectrum in a graph window.
       -c comport           
        Set COM port, 1..4 (default 1)
       -t             
              Use transmission measurement mode
       -e
                          
        Use emissive measurement mode (absolute results)
       -eb
                         
        Use display white brightness relative measurement mode
       -ew
                         
        Use display white point relative chromatically adjusted mode
       -p
                          
        Use telephoto measurement mode (absolute results)
       -pb
                         
        Use projector white brightness relative
        measurement mode
       -pw
                         
        Use projector white point relative
        chromatically adjusted mode
     -a
                          
        Use ambient measurement mode (absolute results)
         -f                   
        Use ambient flash measurement mode (absolute results)
       -y X
                      
 
        Display type - instrument specific list to choose from.
     -I illum      
               Set simulated instrument illumination
        using FWA (def -i illum):
                 
 
 
 
 
 
  
M0,
        M1, M2, A, D50 (def.), D50M2, D65, F5, F8, F10 or file.sp
     -i illum      
               Choose illuminant for computation of
        CIE XYZ from spectral reflectance & FWA:
                 
 
 
 
 
 
  
A,
D50
(def.),
        D50M2, D65, F5, F8, F10 or file.sp
       -Q observ     
               Choose CIE Observer for
        spectral data or CCSS instrument:
                 
                     1931_2  (def.), 1964_10, S&B 1955_2, shaw,
        J&V 1978_2
         -F filter            
        Set filter configuration:
          
        n                   
        None
          
        p                   
        Polarising filter
          
        6                   
        D65
          
        u                   
        U.V. Cut
         -E extrafilterfile   
        Apply extra filter compensation file
         -A N|A|X|G           
        XRGA conversion (default N)
       -x
                          
        Display Yxy instead of Lab
       -h
                          
        Display LCh instead of Lab
     -V
                          
        Show running average and std. devation from ref.
     -T
                          
        Display correlated color temperatures, CRI and TLCI
       -N                   
        Disable initial calibration of instrument if possible
     -O
                          
        Do one cal. or measure and exit
     -H
                    
              Use high resolution spectrum mode
        (if available)
         -R fname.sp          
        Preset reference to spectrum
         -X file.ccmx         
        Apply Colorimeter Correction Matrix
     -X
        file.ccss         
Use
Colorimeter
Calibration
Spectral
Samples
      for calibration
     -Y
        r|n          
             Override refresh, non-refresh display
        mode
     -Y R:rate            
      Override measured refresh rate with rate Hz
     -Y A
                    
            Use non-adaptive integration time mode (if
        available).
     -Y W:fname.sp        
      Save white tile ref. spectrum to file
     -Y L      
                 Test for i1Pro Lamp
      Drift, and remediate it
     -W n|h|x             
Override
serial
port
flow
control:
n
=
none,
        h = HW, x = Xon/Xoff
     -D [level]
                  
        Print debug diagnostics to stderr
     logfile              
        Optional file to save reading results
      
    Usage Details and Discussion
    spotread operates in a similar fashion to  chartread, but allows the reading of a
    succession of single color values. This can be useful in diagnosing
    issues with profile creation and operation.
    
    The -v flag causes extra information to be
    printed out during chartread operation.
    
    The -s flag enables the printing out
    spectral reflectance/transmittance values, if the instrument
    supports this.
    
    The -S flag enables the plotting of the
    spectral reflectance/transmittance values, if the instrument
    supports this. If a reference is taken, this will be plotted in red.
    You must strike a key in the plot window to continue with another
    measurement.
    
    The Graph plots light wavelength on the X axis, and either absolute
    or relative level on the Y axis. 
    
    
    
      
        
          | Measurement Mode 
 | Y Units 
 | 
        
          | Emission 
 | mW/(m2.sr.nm) | 
        
          | Ambient 
 | mW/(m2.nm) 
 | 
        
          | Emission Flash 
 | mW/(m2.sr.nm.s) 
 | 
        
          | Ambient Flash 
 | mW/(m2.nm.s) 
 | 
        
          | Reflective 
 | %/nm 
 | 
        
          | Transmissive 
 | %/nm 
 | 
      
    
    
     The instrument is assumed to communicate through a
    USB or serial communication port, and the port can be selected with
    the -c option, if the instrument is not connected to the
    first port. If you invoke spotread
    so as to display the usage information (i.e. "spotread -?" or
    "spotread --"), then the discovered USB and serial ports will be
    listed. On UNIX/Linux, a list of all possible serial ports are
    shown, but not all of them may actually be present on your system.
    
    If using an Xrite DTP41T or SpectroScanT, and
    printing onto transparent or back lit media, use the -t flag
    to operate the instrument in transparency mode. If using the
    Spectroscan, this triggers a fake transparency mode, that uses a
    separate backlight (such as a light box). The  instrument will
    be used to calibrate the level of backlight, and use this to compute
    the transparency of the test chart samples. Note that for good
    transparency values, the backlight level needs to be neither too
    bright not too dark, should ideally be incandescent rather than
    fluorescent (since fluorescent lights often have big dips in their
    spectrum), and ideally should be of uniform brightness over the
    measurement area.
    
    The -e flag
    allows measuring in emission mode (e.g. displays or illuminants)
    using instruments that support this mode. An adaptive integration
    time will be used in devices that support it by default (see the -ZA flag). Values returned are absolute.
    
    The -eb
    flag allows measuring in emission mode using instruments that
    support this mode, with the brightness reading being relative to the
    white value read as the first reading. While the brightness values
    are then relative to the white, the readings are otherwise absolute.
    This corresponds to the raw ICC absolute readings created by spotread.
    
    The -ew
    flag allows measuring in emissive mode using instruments that
    support this mode, with the reading being relative to the white
    value read as the first reading using a Bradford chromatic adaption.
    This matches the absolute <-> relative intent transformation
    of Argyll ICC profiles.
    
    The -p flag
    allows measuring in telephoto mode, using instruments that support
    this mode, e.g. the ColorMunki. Values returned are absolute.
     Note that you would use normal emissive mode to measure
    projectors using instruments without a specific telephoto mode.
    
    The -pb
    flag allows measuring in telephoto mode using instruments that
    support this mode, with the brightness reading being relative to the
    white value read as the first reading. While the brightness values
    are then relative to the white, the readings are otherwise absolute.
    This corresponds to the raw ICC absolute readings created by spotread.
    
    The -pw
    flag allows measuring in telephoto mode using instruments that
    support this mode, with the reading being relative to the white
    value read as the first reading using a Bradford chromatic adaption.
    This matches the absolute <-> relative intent transformation
    of Argyll ICC profiles.
    
    The -a flag
    allows measuring in ambient illumination mode using instruments that
    support this mode (i.e. Eye-One Display 2). Values returned are
    absolute, and include the various color temperatures and Color
    Rendering Index (see -T).
    If the instrument does not support ambient mode, emissive mode will
    be used instead. An adaptive integration time will be used in
    devices that support it. 
    
    For an instrument that supports it (i.e. the Emulated transmission
    measurement mode of the JETI 1211), then using -a after the
    -t switch will select the alternate 90/diffuse transmission
    geometry (i.e. using the ambient adapter for transmission
    measurement).
    
    The -f flag
    allows measuring a flash with those instruments that support
    scanning emissive measurements. The instrument needs to be triggered
    by holding down its button, triggering the flash, then releasing the
    button, similar to how a reflective strip is read.
    
      The -y
    flag allows setting the Display Type. The selection typically
    determines two aspects of of the instrument operation: 1) It may set the measuring mode
    to suite refresh or non-refresh displays.
    Typically only LCD (Liquid Crystal) displays have a non-refresh
    nature. 2) It may select an
    instrument calibration matrix suitable for a particular display
    type. The selections available depends on the type and model of
    instrument, and a list of the options for the discovered instruments
    will be shown in the usage
    information. For more details on what particular instruments support
    and how this works, see Operation of
      particular instruments. 3) Any installed CCSS files
    (if applicable), or CCMX files. These files are typically created
    using ccxxmake, and installed using oeminst. The default and Base Calibration
    types will be indicated in the usage.
    
    The -I parameter allows specifying a
    standard or custom illumination spectrum to be used as the simulated
    reflectance instrument illuminant when FWA compensation is used
    during measurement, overriding the default D50 or
    CIE computation illuminant used for FWA (see -i below). If
    intending to use standard M0, M1 or M2
    conditions, then use just the -I option and not the  -i
    option. See colprof -f for a fuller
    explanation. 
    
    The -i parameter allows specifying a
    standard or custom reflectance illumination spectrum applied to reflective or transmissive
    spectral data to compute CIE tristimulus values. A,
    D50, D50M2, D65, F5, F8, F10
    are a selection of standard illuminant spectrums, with D50
    being the default. If using -I to obtain standard M0,
    M1 or M2 conditions, then this -i option is not
    normally used. If a filename is specified instead, it will be
    assumed to be an Argyll specific .sp
    spectrum file. If FWA compensation is used during measurement, this
    illuminant will be used by default as the simulated instrument
    illuminant.
    
     The -Q flag allows specifying a tristimulus
    observer, and is used to compute PCS (Profile Connection Space)
    tristimulus values. This is possible for a spectral instrument, or a
    colorimeter that has CCSS capability. The following choices are
    available:
      1931_2 selects the standard CIE 1931 2 degree
    observer. The default.
      1964_10 selects the standard CIE 1964 10 degree
    observer.
      1955_2 selects the Stiles and Birch 1955 2 degree
    observer
      1978_2 selects the Judd and Voss 1978 2 degree
    observer
      shaw selects the Shaw and Fairchild 1997 2 degree
    observer
    
    The -F options allows configuring the
    instrument to have a particular filter fitted to it. Some
    instruments (i.e. the Gretag Spectrolino) allow the fitting of
    various filters, such as a polarizing filter, D65 illuminant
    simulation, or Ultra Violet Cut filter, and this option allows the
    instrument to be configured appropriately.
    
    The -E option allows the setting of an extra
    filter compensation file, that allows for the filtration of the
    spectral readings through a medium of some kind, when in emission
    mode. This is useful in allowing for such things as telescopic
    adapters that use a glass of acrylic lens in the optical path. [Note that this is currently only
    supported by the Spectrolino driver.]
    
    The -A options allows overriding the default
    or environment variable set XRGA
    conversion:
    
        -A N|A|X|G
    
            The N argument sets
    the calibration to Native (default).
            The A argument sets
    the calibration to XRGA.
            The X argument sets
    the calibration to XRDI.
            The G argument sets
    the calibration to GMDI.
    
    The -x option causes the reading to be
    displayed as XYZ and Yxy values, rather than the default XYZ and
    L*a*b*
    
    The -h option causes the reading to be
    displayed as XYZ and LCh values, rather than the default XYZ and
    L*a*b*
    
    The -V enables average and standard
    deviation statistics on the XYZ and L*a*b* values. This start and is
    reset whenever a reference is taken ('r' key). A side effect of this
    option is to disable the clamping of XYZ and L*a*b* value to
    positive, so that a valid average of black can be obtained.This is
    useful in quantifying repeatability.
    
    The -T option causes various color
    temperatures to be displayed, plus the Color Rendering Index. Three
    color temperatures will be shown. The first is the classic
    Correlated Color Temperature, which is the black body (Plankian)
    color closest to the measured color in the CIE 1960 UCS color space.
    The second is the black body (Plankian) color that has a minimum
    CIEDE2000 error to the measured color. The last is the daylight
    color that has a minimum CIEDE2000 error to the measured color. The
    delta E between the closest temperature and the measured color is
    also shown for each. The Color Rendering Index (CRI Ra) including
    the R9 value, plus the TLCI (Qa) is also computed if the instrument
    is capable of spectral measurement. If the notation (Invalid) is displayed after the
    CRI or TLCI, then this means that the the spectrum white point is to
    far from the black body and Daylight locus to be meaningful.
    
     -N Any
    instrument that requires regular calibration will ask for
    calibration on initial start-up. Sometimes this can be awkward if
    the instrument is being mounted in some sort of measuring jig, or
    annoying if several sets of readings are being taken in quick
    succession. The -N
    suppresses this initial calibration if a valid and not timed out
    previous calibration is recorded in the instrument or on the host
    computer. It is advisable to only use this option on the second and
    subsequent measurements in a single session.
    
    -O Do a calibration or a single measurement
    and exit. To take a measurement with an instrument that always does
    a calibration first, calibrate it and then use -O with -N. The -O
    option is intended to simplify scripted use of spotread.
    
     The -H
    option turns on high resolution spectral mode, if the instrument
    supports it. See Operation of particular
      instruments for more details.
    
    The -R fname.sp
      option allows specifying a reference spectrum to preset the
    reference values used to calculate delta E etc. This can be useful
    in checking against a previously saved value ('s' command),
    or in checking the instruments consistency against it's reflective white reference spectrum.
    
     The -X file.ccmx option reads
    a Colorimeter Correction Matrix
    from the given file, and applies it to the colorimeter instruments
    readings. This can improve a colorimeters accuracy for a particular
    type of display. A list of contributed ccmx files is here.
    
     The -X file.ccss option reads
    a Colorimeter Calibration
      Spectral Sample from the given file, and uses it to set the
    colorimeter instruments calibration. This will only work with
    colorimeters that rely on sensor spectral sensitivity calibration
    information (ie. the X-Rite i1d3,
    or the DataColor Spyder4 &
      Spyder5).This can improve a colorimeters accuracy for a
    particular type of display.
    
     The -Y r and
    -Y n options overrides the refresh display mode set by the -y display type selection, with -Y r forcing refresh display mode,
    and -Y n forcing a non-refresh display mode. Not all
    instruments support a display measurement refresh mode, or the
    ability to override the mode set by the display type selection.
    
     The -Y R:rate
    options overrides calibration of the instrument refresh rate. This
    may be useful if the instrument supports this function and the
    refresh rate cannot be accurately calibrated from the display
    itself.
    
     The -Y A
    option uses a non-adaptive integration time emission measurement
    mode, if the instrument supports it, such as the Eye-One Pro,
    ColorMunki, i1d3 or K10. By default an adaptive integration time
    measurement mode will be used for emission measurements, but some
    instruments support a fixed integration time mode that can be used
    with display devices. This may give faster measurement times, but
    may also give less accurate low level readings.
    
    The -W n|h|x
    parameter overrides the default serial communications flow control
    setting. The value n turns
    all flow control off, h
    sets hardware handshaking, and x
    sets Xon/Xoff handshaking. This commend may be useful in workaround
    serial communications issues with some systems and cables. 
    
    The -Y W:fname.sp option allows
    saving an instruments reference white tile reflectance spectrum to a
    file. Reflective instruments use a white reference tile to calibrate
    against, and typically the spectral reflectance of the white tile is
    recorded inside the instrument to calibrate to. The saved spectrum
    can be used to compare against the measurements of a reference grade
    measurement of the white tile to check for tile deterioration, or
    can be used as a reference for checking on instrument calibration
    accuracy or consistency (See the -R option). Not
    all instruments support this option (Currently the Spectrolino,
    i1Pro, i1Pro2 and ColorMunki spectrometer.)
    
     The -Y l|L option is a special function
    for X-Rite i1Pro instruments.
    These instruments use an incandescent lamp as a light source for
    reflectance measurement, and some instruments after some patterns of
    use, can suffer from Lamp output thermal drift, due to the build up
    of filament tungsten on the bulb inner surface. This function first
    measures the Lamp drift, and then if the -Y L version is
    used and the drift is greater than normal (0.06 - 0.1 Delta E), it
    will attempt to remediate the problem by turning the lamp on for
    some seconds so that it reaches normal operating temperature and is
    able to re-circulate the tungsten back onto the filament properly.
    It will then wait for the lamp to cool, and re-measure the drift.
    These operations can take a few minutes, and it is advisable to let
    the instrument cool off further after this operation, for 2 - 5
    minutes, to allow it to return to normal operation conditions.
    
    The remediation function should be used infrequently or if the
    repeatability of the instrument seems to be poorer than usual, as
    frequent use may consume lamp life unnecessarily. If the lamp is
    nearing its end of life, this function may not be effecive.
    
    The -D flag causes communications and other
    instrument diagnostics to be printed to stdout. A level can be set
    between 1 .. 9, that may give progressively more verbose
    information, depending on the instrument. This can be useful in
    tracking down why an instrument can't connect.
    
    The logfile is an optional file that can be specified
    to capture each reading taken. There will be column headers printed
    to the first row, and then each reading will be on a separate line
    with tab separators.
    
    All instruments will be used in a spot mode. For the SpectroScan
    instrument, the samples can be placed on the table, and the
    measuring head positioned before taking a measurement. Note that the
    default mode (reflectance measurement) may not be supported by the
    instrument, so a mode it does support will be selected
    automatically. Override this on the command line if desired. Note
    that the DTP51, DTP92, DTP94 and Eye-One Display are colorimeters,
    and cannot read spectral information, and that the DTP92 can only
    read CRT type displays.
    
    
    Once spotread has established communications with the
    instrument, it awaits a command from the user, indicated by the user
    hitting a key or activating the instrument switch. XYZ values are in
    the range 0 .. 100 for reflective or transmissive readings, and
    absolute cd/m^2 for display, emissive and ambient readings.
    
    By default the L*a*b* values are computed relative to a fixed D50
    100 scale white point, so values for emissive sources are not
    particularly useful.
    Using the display white relative mode uses a Bradford chromatic
    transform to transform from the measured white to a D50 white (the
    same as ArgyllCMS ICC profile deals a display white), and then
    computes the D50 L*a*b from that.
     
    If Fluorescent Whiter Additive (FWA) compensated readings are to be
    made, then this needs to be enabled with the correct command line
    switches, and then setup for each paper white background color, to
    establish an FWA reference. There is one FWA reference locations
    available for each alphabetic character not used for a special
    function (ie. not H, K, N, Q, R,
      S, F), keyed to the capital letters A-Z,
    allowing FWA corrected comparisons between many different media.
    
    Once a particular reference location is initialized with the FWA
    paper color, subsequent readings triggered by using the
    corresponding lower case letter a-z
    will use FWA compensation for that keyed location. Note that
    readings that are triggered some other way (ie. using a non
    alphabetic key, or using the instrument switch) will not be FWA
    corrected readings.
    
    If a non-FWA readings is to be performed, then a reading for a
    location that has not been initialised for paper white should be
    used, or a non alphabetic key (such as space or return) or
    instrument switch trigger should be used.
    
    If the instrument supports a high resolution spectral mode, then it
    can be toggled on and off using the h key.
    
    If the instrument supports a laser target (such as the JETI
    specbos), then this can be toggled on & off using the t
    key. It will automatically be turned off at each measurement.
    
    If the instrument supports stored readings (ie. DTP20), then these
    can be ignored using the n
    key.
    
    The previous reading can be stored as a reference, and delta E's
    computed for each reading, using the r key.
    
    A previous spectral reading can be saved in a spectrum CGATS file
    (spectrum.sp) using the s
    key, making this a convenient way of creating a custom illuminant
    spectrum.
    
    A calibration can be initiated using the k key.
    
    For instruments that support it and are in a refresh display mode,
    the calibrated refresh rate can be read back using the f
    key.
    
    For instruments that support it and are in an emissive measurement
    mode, a display refresh rate measurement can be made by using the F
    key.