scanin
Author: Graeme Gill

## scanin/scanin

### Summary

Convert an 8 or 16 bit per component TIFF image of a test chart into .ti3 device values using automatic pattern recognition, or manual chart alignment.
Performs other tasks associated with turning a TIFF raster of test patches into numeric values.

### Usage Summary

usage: scanin [options] input.tif recogin.cht valin.cie [diag.tif]
:- inputs 'input.tif', and outputs scanner 'input.ti3', or
usage: scanin -g [options] input.tif recogout.cht [diag.tif]
:- outputs file 'recogout.cht', or
usage: scanin -o [options] input.tif recogin.cht [diag.tif]
:- outputs file 'input.val', or
usage: scanin -c [options] input.tif recogin.cht scanprofile.[icm|mpp] pbase [diag.tif]
:- inputs pbase.ti2 and outputs printer pbase.ti3, or
usage: scanin -r [options] input.tif recogin.cht pbase [diag.tif]
:- inputs pbase.ti2+.ti3 and outputs pbase.ti3
-g Generate a chart reference (.cht) file
-o Output patch values in .val file
-c Use image to measure color to convert printer pbase .ti2 to .ti3
-ca Same as -c, but accumulates more values to pbase .ti3
from subsequent pages
-r Replace device values in pbase .ti3
Default is to create a scanner .ti3 file
-F x1,y1,x2,y2,x3,y3,x4,y4
Don't auto recognize, locate using four fiducual marks
-p Compensate for perspective distortion
-a Recognize chart in normal orientation only
Default is to recognize all possible chart angles
-m Return true mean (default is robust mean)
-G gamma Approximate gamma encoding of image
-v [n] Verbosity level 0-9
-d [ihvglLIcrsonap] generate diagnostic output (try -dipn)
i diag - B&W of input image
h diag - Horizontal edge detection
v diag - Vertical edge detection
g diag - Groups detected
l diag - Lines detected
L diag - All lines detected
I diag - lines used to improve fit
c diag - lines perspective corrected
r diag - lines rotated
s diag - sample boxes rotated
o diag - sample box outlines
n diag - sample box names
a diag - sample box areas
p diag - pixel areas sampled
-O outputfile Override the default output filename & extension.

### Usage Details and Discussion

scanin is setup to deal with a raster file that has been roughly cropped to a size that contains the test chart. It's exact orientation is not important [ie. there is usually no need to rotate or crop the image any more finely.] The reference files are normally set up with the assumption that the edges of the chart are visible within the image, and if the image is cropped to exclude the chart edges, it may well not recognize the chart properly. It is designed to cope with a variety of resolutions, and will cope with some degree of noise in the scan (due to screening artefacts on the original, or film grain), but it isn't really designed to accept very high resolution input. For anything over 600DPI, you should consider down sampling the scan using a filtering downsample, before submitting the file to scanin. Similarly, any file with a large level of noise (due to screening or scanner artefacts) should consider down sampling the image or filtering it with some average preserving filter before submitting it to scanin. Examining the diagnostic output (ie. -dig and -dil) may help in determining whether noise is an issue.
There are 5 basic modes that scanin operates in.

- When no special argument is given scanin is assumed to be parsing an input device characterization chart (ie. an IT8.7/2 chart), for the purpose of creating a .ti3 data file containing the CIE test values and the corresponding RGB scanner values. The .ti3 file can then be used for creating an input profile using colprof. The file arguments are: The TIFF file that is to be processed, the image recognition template file, the CIE reference value definitions for the test chart (sometimes labeled a ".q60" file), and an optional name for the image recognition diagnostic output. The resulting .ti3 file will have the same base name as the input TIFF file.
- If the -g flag is specified, then scanin is operating in a mode designed to create the necessary image recognition template file (.cht) boilerplate information. Patch location and labeling information would need to be added manually to such a generated file, to make a complete and useable recognition template file. CHT file format. The input TIFF file in this situation, should be a good quality image, perhaps synthetically generated (rather than being scanned), and perfectly oriented, to make specification of the patch locations easier. The file arguments are: The TIFF file that is to be processed, the image recognition template file to be created, and an optional name for the image recognition diagnostic output.
- If the -o flag is used, then scanin will process the input TIFF file and produce a generic CGATS style file containing just the patch values (a .val file). The file arguments are: The TIFF file that is to be processed, the image recognition template file to be created, and an optional name for the image recognition diagnostic output.
- If the -c flag is used, then an input image of a print test chart can be used in combination with a device profile, to estimate the CIE tristimulus values of the patches. This allows RGB input devices to be used as a crude replacement for a color measuring instrument. The icc or mpp profile has (presumably) been created by scanning an IT8.7/2 chart (or similar) through the RGB input device, and then using scanin to create the .ti3 file needed to feed to colprof to create the input device profile. The file arguments in -c mode are: The TIFF file that is to be processed containing the image of a print test chart, the image recognition template file for the test chart generated by the printtarg tool, the input device ICC or MPP profile, the base name for the .ti2 file containing the test chart printer device values and their patch identifiers and the base name for the resulting .ti3 file, and finally an optional name for the image recognition diagnostic output. The resulting .ti3 file will have the same base name as the input TIFF file. If there is more than one page in the test chart, then scanin will need to be run multiple times, once for each scan file made from each test chart. The -ca flag combination should be used for all pages after the first, as this then adds that pages test values to the .ti3 file, rather than creating a .ti3 file that contains only that pages test values. If the incoming .ti2 file contains per-channel calibration curves, these will be passed through to the .ti3 so that accurate ink limits can be computed during profiling.
- If the -r flag is used, then the input TIFF value is used as a source of device values to replace any existing device values in the given .ti3 file. This is intended for use in the situation in which the device values being fed into an output device are altered in some way that is difficult to predict (ie. such as being screened and then de-screened), and this alteration to the device values needs to be taken into account in creating a profile for such a device. The file arguments in -r mode are: The TIFF file that is to be processed containing a rasterized image of an output test chart, the image recognition template file for the test chart generated by the printtarg tool, the base name for the .ti2 file containing the output test chart device values and their patch identifiers and the base name for the .ti3 file that is to have its device values replaced, and finally an optional name for the image recognition diagnostic output.

A number of flags and options are available, that are independent of the mode that scanin is in.
Normally scanin will try and recognize a chart, irrespective of its orientation. For charts that have some asymmetric patch size or arrangement (such as an IT8.7/2, or a chart generated by printtarg with the -s option), this is both flexible and reliable. Other charts may be symmetrical, and therefore having scanin figure out the orientation automatically is a problem if the recognition template does not contain expected patch values, since it will have an equal chance of orienting it incorrectly as correctly. To solve this, the -a flag can be used, and care taken to provide a raster file that is within 45 degrees of "no rotation".
Normally scanin will use automatic chart recognition to identify the location of the test patches and extract their values. If the chart CHT file has four fiducial marks defined, then the chart can be manually aligned by specifying the pixel location of the four marks as arguments to the -F flag. The top left, top right, bottom right and bottom left fiducial marks X and Y co-ordinates should be specified as a single concatenated argument, separated by comma's, e.g: -F 10,20,435,22,432,239,10,239 The coodinates may be fractional using a decimal point. Four fiducial marks allows for compensation for perspective distortion.
By default the automatic chart recognition copes with rotation, scale and stretch in the chart image, making it suitable for charts that have been scanned, or shot squarely with a camera. If a chart has been shot not exactly facing the camera (perhaps to avoid reflection, or to get more even lighting), then it will suffer from perspective distortion as well. The -p flag enables automatic compensation for perspective distortion.
Normally scanin computes an average of the pixel values within a sample square, using a "robust" mean, that discards pixel values that are too far from the average ("outlier" pixel values). This is done in an attempt to discard value that are due to scanning artefacts such as dust, scratches etc. You can force scanin to return the true mean values for the sample squares that includes all the pixel values, by using the -m flag.
Normally scanin has reasonably robust feature recognition, but the default assumption is that the input chart has an approximately even visual distribution of patch values, and has been scanned and converted to a typical gamma 2.2 corrected image, meaning that the average patch pixel value is expected to be about 50%. If this is not the case (for instance if the input chart has been scanned with linear light or "raw" encoding), then it may enhance the image recognition to provide the approximate gamma encoding of the image. For instance, if linear light encoding ("Raw") is used, a -G value of 1.0 would be appropriate. Values less than 2.2 should be tried if the chart is particularly dark, or greater than 2.2 if the chart is particularly light. Generally it is only necessary to provide this is there are problems in recognizing the chart.
The -v flag enables extra verbosity in processing. This can aid debugging, if a chart fails to be recognized.
The -d flag enables the generation of an image recognition diagnostic raster. The name of diagnostic raster can be specified as the last in the command line, or if not, will default to diag.tif. Various flags control what is written to the diagnostic raster. Note that at least one flag must be specified for a diagnostic raster to be produced.
i creates a black and white version of the input raster in the diagnostic output, to be able to compare with the feature extraction.
h will show pixels in the input image classified as being on horizontal edges, in red.
v will show pixels in the input image classified as being vertical edges, in green.
g will show groups of pixels that will be used to estimate edge lines, each group in a different color.
l will show valid lines estimated from the vertical and horizontal pixel groups, in white.
L will show all lines (valid and invalid) estimated from the vertical and horizontal pixel groups, in white.
I will show valid lines lines used to improve the final fit, in blue.
c will show the lines with perspective correction applied in cyan.
r will show the lines rotated to the reference chart orientation, in yellow.
s will show the diagnostic sampling box edge outlines, rotated to the reference chart orientation, in orange.
o will show all the sampling box edge outlines, in orange.
n will show the ID names of the sampling boxes, plus the diagnostic sample boxes, using a simple stroke font, in orange.
a will show the sampling areas as crossed boxes, plus the diagnostic sample boxes, in orange.
p will show the sampling areas as colored pixels.
The combination of -dipn is usually a good place to start.
The TIFF file can be either 8 or 16 bits per color component, with 16 bit files being slower to process, but yielding more precise results.
If at all in doubt that the file has been recognized correctly, use the -dipn diagnostic flag combination, and check the resulting diagnostic raster file.
[ A badly recognised image will typically result in high self fit delta E's when used with colprof. ]
The -O parameter allows the output file name & extension to be specified independently of the last tiff filename. This works for the default, -g and -o modes. It is ignored for the -r, -c and -ca modes that use a basename for .ti2 in and .ti3 output. Note that the full filename must be specified, including the extension.