USER'S MANUAL
for
RGBcal  and  DyEye
 
Color Image Analysis Programs
by
Toby Ewing
Department of Agronomy,
Iowa State University, Ames, IA
 
 
 
 
 
 Back to Color Page
  • Overview 
  • Legal Stuff 
  • Requirements 
  • Distribution Files 
  • General Operation
  • RGBcal 
  •     File 
  •     Correlation
  •     View 
  •     Regress 
  •     Output 
  •     Setup 
  • DyEye 
  •     File 
  •     Configure 
  •     Zoom 
  •     Enhance 
  •     Threshold 
  •     Output 
  •     Setup 
  • References 
  • Appendix A: TIFF file issues 
  • Appendix B: Program Error Codes 
  • Appendix C: Recovery and Config File Formats 
  • Appendix D: Program Support and use of Source Code 

  • Overview:

    RGBcal and DyEye are tools for analyzing RGB (Red-Green-Blue) color images on DOS-based microcomputers. Their purpose is to transform an RGB image via some equation into quantitative information. This information can be boolean, denoting the presence or absence of some characteristic (e.g., plant versus soil; see Ewing and Horton, 1998a), or it may be continuous (e.g., the concentration of dye on the soil surface; see Ewing and Horton, 1998b). RGBcal is used to develop and calibrate the transforming relationship, and DyEye is used to effect the transformation. Both programs work with uncompressed TIFF (tag image file format) files, a common raster image file format recognized by most scanners, digital cameras, image editing programs, and even many word processors. TIFF files with full RGB information are also called 24-bit TIFF, or (sometimes) True Color. The programs were designed to be used on small DOS-based computers, but are capable of working with quite large image files. The programs and portions of the source code are in the public domain. The programs were originally developed with agronomic applications in mind, as reflected in the examples, but they are in no way restricted to that field.

    Top    Next


    Legal Stuff:

    RGBcal and DyEye were written in Pascal and compiled using Turbo Pascal 7.0 (copyright © 1983, 1992 Borland International, Inc., Scotts Valley, CA).  Portions of the program copyright © 1983, 1987, 1989, 1992 Borland International, Inc., all rights reserved.  The graphics driver distributed with the program is copyright © 1991, 1993, Knight Software.  The program author, Borland International, Inc., and Iowa State University (ISU) are not liable for any aspect of these programs, nor do they guarantee their functionality or accuracy.  Mention of a specific product in this manual does not imply endorsement by ISU, nor criticism of similar products not mentioned.

    Top    Previous     Next


    Requirements:

    The programs require an DOS machine with approximately 512K of available RAM and the DOS operating system (version 2.11 or greater). The executable files were optimized for 80286 and later microprocessors with a math coprocessor (required). A graphics display (SVGA, 1024 x 768 x 256 colors, hence 1 MB vRAM) is required: if your display is not up to this level, the program will run, but you won't see what it is doing, so interacting with the program will be difficult!

    The design philosophy behind these programs is simply that processing of large images should not be limited to huge power-hungry computers, but should be available to lowly DOS machines as well.  Of course, this idealism comes at a cost: a bigger machine may read in an image once and hold several copies of it (at different stages of processing) in memory, allowing it to perform operations almost instantaneously.  These programs will need to read the image in many times, and will hold only a few lines in memory at any given moment. The need to read the image many times slows the processing (although using a disk cache alleviates much of this problem), and holding only a few lines in memory limits DyEye to only one filter operation per image.  Within these constraints, the programs can handle larger images than many programs much more powerful (and expensive).  Because the programs only hold a few lines at a time, files of several megabytes in size can be processed.  The TIFF specification limits both image width and length to 65536 pixels, but these programs are theoretically limited to widths of approximately 16,380 pixels.  The actual width they can handle will change depending on how many files you use for calibration (in RGBcal), and how many color parameters your equation has and how large your mask processor is (in DyEye).

    If your computer tells you there is not enough memory to run the program then you may need to close your graphical interface and run in DOS without TSRs or other memory resident programs loaded. I have not encountered any problems running these programs under a graphical interface in a full-screen DOS box (with no background jobs). If your graphical interface requires a .PIF file, you should run in full-screen mode and allocate memory for high-resolution graphics. I also recommend that you not have the window close automatically upon exit.

    Top    Previous     Next


    Distribution Files

    To run RGBcal and DyEye, you'll need the following files:
     
      RGBCAL.EXE 
      DYEYE.EXE 
      BGI256.BGI 
      MANUAL.TXT, or 
      MANUAL.WP5, or 
      MANUAL.HTML
    The RGBcal executable 
    The DyEye executable 
    The graphics driver (small) 
    This manual, text version, or 
    This manual, WP 5.1 format, or 
    This manual, HTML version.
    In addition to these, the following source code and related files are available at the same web site:
      RGBCAL.PAS 
      RGBGRAPH.PAS 
      NONLIN.PAS 
      DYEYE.PAS 
      DYGRAPH.PAS  
      INTFACE2.TPU 
      INTFACE2.INT
    The RGBcal main program file 
     RGBcal graphics & other routines 
    The nonlinear curve-fitting code 
    The DyEye main program file 
    DyEye graphics & other routines 
    The interface unit (compiled) 
    The interface to the interface unit (!)
     
    Top    Previous     Next


    General Operation:

    The programs are started from the DOS prompt in their home directory (e.g. c:\color) by entering the command RGBcal (or DyEye). The opening screen will show a window with program information (title, version and date), and a menu bar at the top. Menu selections can be made by entering the first letter of the command, or by using the left and right arrow keys to move from one menu entry to another and then hitting the <Enter> key when the desired menu entry is highlighted. Each of the menu entries can be exited at any time using the <ESC> key. The program can be exited at any time by hitting <alt-x>. The programs do not recognize a pointing device such as a mouse.

    Within the dialog boxes of each menu entry the up and down arrow keys, or the left and right tab key, are used to move from one box to another. The space key (or alternatively the right arrow key) is used to mark or to "toggle" choices. In some boxes a numerical entry or filename is required, and here normal editing keys, such as the home, end, insert, and delete keys, have their normal functions. If the current setting is desired the <Enter> key is pressed or the arrow keys can used to bypass the box. Pressing <Enter> when an "OK" box is highlighted will close the dialog window and your choices will be kept. Pressing <ESC> anywhere in a dialog window will close the window, and the previous selections will be kept. Within graphical dialogs, boxes along the left edge of the screen are selected by entering the first letter of the box (e.g., "F" for the File box), and other graphical windows are available by pressing the first letter of their menu selection. For example, in DyEye's Zoom menu, you can get to the Enhance menu just by pressing "E". Within each graphical box, only certain keystrokes are recognized.

    Top    Previous     Next


    RGBcal:

    RGBcal is a tool for developing a calibration equation relating color parameters (e.g., red, hue) to some independent parameter of interest (e.g., dye concentration, nitrogen status of a crop). A useful calibration equation will be based on those color parameters that change most clearly and unambiguously as the independent parameter changes, so correlation and visualization tools are included in RGBcal. The equation is developed and its parameters optimized using RGBcal's nonlinear regression package. Sometimes it is useful to output an image in data format (for example, for export to a more advanced statistical package), so RGBcal can also do that. The equation and related information from RGBcal is put into a small file (DYEYE.CFG) which is read by DyEye upon startup.

    RGBcal takes as input up to 1024 calibration images. Each file should correspond to a known value of the independent parameter. In our work, we construct these files using the software that came with our color scanner -- any TIFF editor will do. We find areas in our (big) calibration image(s) that correspond to known values (such as known dye concentrations), select and copy them, then paste them into a new file, which we save in uncompressed TIFF RGB format.

    If the objective is to segment images according to some relationship rather than to obtain continuous quantitative data, then many files may not be needed. If RGBcal is given only a single file, it will notify you that it cannot perform regression, but the other tools -- correlation, color space visualization, and output -- will work.

    Implicit in the very concept of these programs is the idea of consistency. All the images must be acquired and processed the same way if color is to be interpreted as consistent values. For example, if you are separating on the basis of red, illumination differences can wreak havoc with your results: perhaps redness (red / intensity) would be safer. If you have been using direct sunlight, and you supplement it with fluorescent or even incandescent lighting on a foggy day, recalibrate. If you have been acquiring images using a 35mm camera and you change to a digital camera, or if you change film speed or paper gloss, recalibrate. Be especially careful about automatic corrections that are built into many photographic processes: cameras, automated film development systems, and scanners often compensate automatically for low contrast and high or low light levels.

    Top    Previous     Next 



    DyEye:

    DyEye is the production end of the two programs. DyEye uses the equation developed in RGBcal to transform images from color (RGB) values to parameter values. (Greyscale and palette-color TIFF images can also be read in, displayed, and manipulated, but they cannot be transformed by the equation, and the program will not recognize the palette assignments in palette-color images.) The resulting parameter image can be manipulated to constrain the calculated pixel values between user-selected values. The image can also be enhanced through some basic image processing filters, and thresholded if the desired output is boolean rather than continuous. The final image can be output as a TIFF file (binary, greyscale, or palette-color), or as ASCII text.

    The remarks given for RGBcal concerning consistency in image acquisition apply equally, if not more so, to DyEye: if images are not acquired under consistent conditions with respect to lighting, light quality, and automatic correction in any of the various steps of image acquisition, there is no guarantee that the resulting interpretation of the image will be correct. Likewise, remarks concerning optimizing your equation for RGBcal apply even more so here, as the images you send to DyEye are likely to have more points than the number of files you input to RGBcal.

    Top    Previous     Next




     
    References:
     
    Barak, P., J. A. E. Molina, A. Hadas, and C. E. Clapp. 1990. Optimization of an ecological model with the Marquardt algorithm. Ecol. Model. 51:251-263.

    Ewing, R. P. and R. Horton. 1998a. Quantitative color image analysis of agronomic images. Submitted to Agron. J.

    Ewing, R. P. and R. Horton. 1998b. Discriminating dyes in soil with color image analysis. Submitted to Soil Sci. Soc. Am. J.

    Kaspar, T. C. and R. P. Ewing. 1997. RootEdge: Software for measuring root length from desktop scanner images. Agron. J. 89:932-940.

    Top    Previous     Next


    Appendix A: TIFF File Issues

    The TIFF (Tag Image File Format) reader in RGBcal and DyEye was developed using the TIFF revision 6.0 specifications (June 3, 1992, Aldus Corporation, Seattle, WA), but it is not a full TIFF reader. Images produced by scanners tend to be relatively simple, and the programs' capabilities reflect this. The programs assume that the internal format is either continuous or stripped. TIFF 6.0 supports many forms of compression and many forms of internal image storage, but these programs do not. If your files are compressed or have a complex internal format that the programs cannot handle, try reading them into a commercial image or paint program, then saving them under a new name in uncompressed TIFF format.

    If you attempt to read in an image that is not in TIFF format, or a TIFF-format image whose header the programs cannot understand, they will display a file inspection dialog box. You will be asked for the image height and width in pixels, the size of the header in bytes, the number of bits per pixel, whether this is a black/white/grey image or an RGB (red-green-blue) image, and whether the image is a negative (i.e., a pixel value of 0 represents the color white). If the image portion of the file is constructed like a simple TIFF image -- pixels arranged sequentially, left to right and top to bottom like words on a page -- the programs should be able to read the image. However, you will have to enter the image information for each file, each time the programs runs through the files: this can be tedious!

    TIFF tags that RGBcal and DyEye recognize:
    254 Subfile. File must have no subfiles. 
    256 Width. File width must be less than or equal to 16380 pixels (due to memory limitations).
    257 Height. File height may not exceed 65536 pixels. This is part of the standard TIFF specification.
    258 Bits per sample. Valid entries are 1, 4, and 8; RGB samples should be 8.
    259 Compression. File may not be compressed (valid entry is 1).
    262 Photometric interpretation. Valid entries are 0 through 3. 0 and 1 are for grey-scale, 2 means RGB, and 3 is palette-color (each pixel-value is assigned a color through a color table). The programs can read palette-color files, but there is no guarantee that thresholding them will yield meaningful results, so the programs issue a warning flag when it encounters these files.
    273 Strip offsets. Most scanner files will have only one strip, but some will have several.
    277 Samples per pixel. Valid entries are 3, denoting RGB, and 1, denoting other.
    278 Rows per strip. May not exceed 65536.
    279 Strip byte counts (number of bytes in a strip).
    282 X-resolution in pixels per unit (see tag 296).
    283 Y-resolution in pixels per unit.
    284 (Optional) planar configuration. Must equal 1 (chunky format).
    296 Units. Valid entries are 2 (dpi) and 3 (dpc), otherwise the image is unitless.
    320 Color map. This points to the map of the color palette in palette-color images.
    Top    Previous     Next


    Appendix B: Program Error Codes
     
    The equation parser checks the equation you enter, and will issue an error comment if it detects an error. Some error messages are issued upon input (during the initial equation parsing), and some are issued during equation interpretation. These comments are generally self-explanatory, but are elaborated somewhat here.

    Equation Parser Error Codes:
    0 OK -- the equation is formatted and/or executed with no errors
    1 Blank string / no formula -- you must enter an equation
    2 Mismatched/unequal parentheses -- most likely a '(' is missing
    3 Badly formed number -- e.g. 132..3 (double decimal point)
    4 ')' expected
    5 Sqrt of negative number
    6 Log of zero or negative number
    7 Unrecognized function
    8 Invalid character -- for example, '@' and 'z' do not appear in any of the recognized functions or variables.
    9 Double operation -- for example, 14-*6
    10 Illegal exponentiation -- for example, -2.5^-2.5
    11 Division by zero
    12 Badly formed equation -- usually indicates that the equation ended before it should have (for example, 15+19*)
    13 Indeterminate problem -- there is a problem, but the parser cannot determine its exact nature.
     
    If the program actually crashes and prints out an error code, it will be a code generated by the compiler. This code may help you to figure out the problem. Because this error code, and the progress of the optimization iterations are useful clues in the event of a crash, I recommend that if you run RGBcal under a graphical interface, you prevent it from returning directly to that interface when the program quits -- such a return would erase the clues.
     
    Errors you may encounter are:
    100-199  I/O errors (typically disk and/or file problems, such as disk full, or file in use).
    200 Division by zero -- this would be in the curve-fitting code rather than in the parsed equation, which would trap the error as mentioned above. Often results from a fitting parameter changing sign. May indicate an inappropriate equation for the data set: equations that fit nicely rarely produce this error.
    203 Out of heap memory. Options to fix this include: don't use a graphical interface, change your system configuration (i.e., don't use a network, drop your CD driver), use smaller image files, or (if this error shows up in DyEye) simplify the equation. This shouldn't happen unless you're using pretty large files, and even then, the program should display its own error message rather than crashing.
    204 Invalid pointer operation - a problem with memory allocation or deallocation. If you can reproduce the sequence of events that caused it, contact me: I would like to know what lead up to it, and I may be able to fix it.
    205 Floating point overflow - result of a numerical operation is too great.
    206 Floating point underflow - result of a numerical operation is too small.
    207 Invalid floating point operation. This can result from attempting to take the square root of a negative number, or attempting to take the logarithm of zero or a negative number. It can also result from an equation that is too complex, overloading the math coprocessor's stack. Because the math coprocessor typically holds only 8 results on its stack, complex equations that require the storage of many temporary variables can overload the stack. You can avoid this by using simpler equations, or by rearranging your equation so that fewer intermediate results need to be stored.
    Top    Previous     Next


    Appendix C: Recovery and Config File Formats
     
    RGBcal will produce an ASCII file called 'RGBCAL.TMP' before attempting to perform nonlinear regression. If this file is found upon startup, it will read in the information and be ready to continue (of course, you should modify the equation before continuing!). The identical format, through line 14, is used by the DYEYE.CFG file.

    The file format is as follows:
     
    Lines 1-9 Principal components eigenvectors: first the R, G, and B values corresponding to principal component 1, then the same for 2 and 3.
    Line 10 Hue offset (0..2 pi)
    Line 11 The equation, in RGBcal format
    Lines 12-14 Initial values of the parameters A, B, and C
    Line 15 The number of non-white, non-black pixels across all the calibration files.
    Line 16 The directory where the image files are located
    Lines 17+ A list of image file names followed by their corresponding independent parameter values.
    If RGBcal finds a problem in reading in this file, it will minimally prompt you for independent parameter values for each of the image files; at worst it will retain no information at all.

    You can produce your own files in this format, and invoke them at startup by typing, for example, RGBcal DEFAULT.LST. Assuming the file DEFAULT.LST is in the current directory and conforms to the format given above, the values will be loaded and ready for use.

    Top    Previous     Next


    Appendix D: Program Support and Use of Source Code

    RGBcal and DyEye are provided as-is, with no guarantee of technical support, bug fixes, or future upgrades. However, I try to support the programs as best I can, so if you have a question or need help getting them to work, drop me a line.

    The programs are distributed with source code for everything but the rudiments of the user interface (screen-handling and some basic input/output functions). The reason for leaving out these portions is that key parts were written by Borland, and I don't have the right to distribute them as such. However, the compiled version of the interface is included with the distribution files, and I've given an outline of what is available in it, so you can still use it - you just can't modify it.

    I have several purposes in distributing the source code with the programs. First, I want you to have access to the code so that if something goes wrong, or the program does something you don't understand, you can examine the code and discover the reason. If you discover bugs and see how to fix them, I'd appreciate being informed of this so I can maintain the code.

    Second, writing this program has been an education for me. If you can benefit from looking over the code and seeing how I do something, that's great. Also, if you see a better way of doing something, I'd appreciate hearing about it. Along this line, I should admit up front that the interface in the graphical menus is poorly coded - I'm sorry, but I didn't have time to put together a really smooth interface here. I am in the process of learning Delphi, but it will be a while before I translate the programs.

    Finally, you may find that the code can do almost, but not quite, everything that you want to do. Image analysis applications are often custom-built for exactly this reason: each application has its own specific requirements. If you have access to the code, you can easily write another procedure and slip your specific needs into my framework. Once again, I ask that you inform me of what you wanted and how you went about getting it: this way, others may benefit from your effort.

    Top    Previous