KEYWORD scale color_parameters method opacity priority scaling_menu DESCRIPTION : BlendColors BlendColors allows you to assign a different color to each wave while also giving you the capability to tailor the color to fit your own preferences. Normally, you would use BlendColors to generate images for inclusion in publications or presentations. BlendColors generates colors by combining 3 primary colors, red, green, and blue: any color BlendColors uses is represented by three values between zero and one where each value indicates the strength of the contribution from one of the primaries. As an example, the color with a red component of 0.55, a green component of 0.13 and blue component of 1 is a shade of purple. When you use BlendColors you will assign a color (some combination of red, green, and blue) to each wavelength in your input data. When BlendColors calculates the color for a point in the output it will use a weighted combination of the colors of the input wavelengths; the weights are the scaled intensity at the point in each wavelength. With the way Priism stores image files, BlendColors' output will have either three or four "wavelengths". The first three "wavelengths" hold the red, green, and blue components, respectively, for the result of the weighted combination of the input colors. The optional fourth "wavelength" holds the opacity, how opaque a pixel is; the opacity is useful when constructing volume renderings of your data. Tuning how the input is scaled is an important part of getting good looking results from BlendColors. It is generally easiest to do some of that tuning prior to running BlendColors: load your data into an image window, turn on RGB display for that image window, and then use the Image->Scale menu entry in the image window to adjust the scaling for the different wavelengths so that the relative brightness of the different wavelengths is close to what you want in the final output. For instance, if you wanted to limit the contribution from one wavelength, you would stretch the maximum scaling value well past the upper limit for that wavelength's data values. After you have done the initial tuning of the scaling, use the image window where you did the tuning as the input to BlendColors: BlendColors will automatically pick up your modified scaling values. Another aid for tuning the scaling is BlendColors' scaling menu. It works after you have done an initial run with BlendColors: if you saved the output from that run to an image window, the you can use the scaling menu to adjust the scaling and see the effect on the currently displayed section of the blended result. After you have refining the scaling with the scaling menu, you would then press "DoIt" again in BlendColors to ensure that the updated scaling has been applied to all sections of the output. A basic recipe for using BlendColors is 1) (optional) Load the data you wish to blend into an image window and tune the scaling to get close to the desired balance between the wavelengths. 2) Enter the image window (i.e. the one used in step one) or file name to process in the "Open" field at the top of the BlendColors dialog. 3) Enter the image window or file name for the output in the "Save" field near the top of the BlendColors dialog. If you use an image window for the output, you can use the scaling menu to refine the scaling parameters once you have done one run through BlendColors. 4) Choose the colors to use for each input wavelength. To see the current selection of colors or to load or save color parameters, use the "color parameters..." button in BlendColors' main dialog. To select a color from a color wheel and use that color for a particular wavelength, press the "color wheel..." button in BlendColors' main dialog. Some things to keep in mind as you select colors are: The COLORS directory at the top level of the Priism directory has color parameter files that others found to be useful. When you select colors, dark blue is a poor choice and will not print well. If you are going to print the picture, some software (the Image->Print menu entry in Priism's image windows, for instance) is not intelligent enough to ensure that the printed colors match what you see on the screen. If the software can't help you to match the colors, one rule of thumb, especially if you are printing to transparencies, is to choose your colors and scaling so the image appears somewhat brighter than you want when you display it on the screen. 5) Select the method to use for blending the colors from the different wavelengths. If you plan to use the output for volume rendering, you probably want to turn on the "opacity" toggle button as well (you could also wait to do so until you've finished refining the scaling parameters). 6) Press the DoIt button at the bottom of the BlendColors dialog to generate the blended result. 7) (optional) If the output was written to an image window, you can use BlendColors' scaling menu to adjust the scaling parameters at this point. Once you've adjusted those to your liking, pressing "DoIt" again will ensure that the output is completely consistent with the adjusted parameters. BlendColors accepts the command-line arguments described in Region.hlp. In addition, it has the following options (parts in brackets are optional): -color1=r:g:b Sets the red (r), green (g), and blue (b) components for the color assigned to the first wavelength in the input. There are similar options (-color2, -color3, -color4, and -color5 to set the colors for the other wavelengths). If you do not set the color for a wavelength with a -color1 (-color2, ...) or -colors option, BlendColors will use black if you do not have a default color file or will use the color in your default color file. -colors=color_file Causes BlendColors to use the colors in color_file as the colors it assigns to the wavelengths in the input. A -colors option will override any previous -color1 (-color2, ...) or -colors options that appear on the command line. -lowest_priority=i Specifies that the wavelength with the zero-based index, i, in the input will be lowest priority wavelength for the priority blending algorithm. By default, BlendColors uses the first wavelength in the input file as the lowest priority wavelength. -method=name Sets the algorithm BlendColors uses to blend different wavelengths. The allowed values for name are additive, max_intensity, and priority. For more information about those algorithms, consult the method topic. If you do not explicitly set a method, BlendColors will use the additive algorithm. -opacity If set, BlendColors will generate output with four wavelengths where the fourth wavelength stores the opacity. -scl1=bound1[:bound2[:exp[:flag]]] Sets the scaling parameters for the output drawn from the first wavelength of the input. Takes one to four parameters; parameters not specified take on their default values (see the scale topic for what the default values are). The first two parameters are the intensity bounds for scaling, the third is the exponent, and the fourth sets what happens to data values outside of the intensity bounds. The documentation for the image window's Scale function describes the parameters in more detail. There are similar options (-scl2, -scl3, -scl4, and -scl5 to set the scaling for the other input wavelengths).

The following example generates the blended result, blend.dat, from fish.dat and the color parameter file, scotts.blend, in the Priism COLORS directory. The example uses the priority blending algorithm with the second wavelength in the input as the lowest priority wavelength. 

    BlendColors fish.dat blend.dat -colors=${IVE_BASE}/COLORS/scotts.blend \
        -method=priority -lowest_priority=1

scale
    Before blending the different wavelengths, BlendColors
    scales the data.  The parameters controlling the scaling
    (a minimum, maximum, exponent, and flag value) for
    each wavelength are shown in the "scale 0" through
    "scale 4" fields in BlendColors' main dialog.  For
    more details about the scaling calculation and the
    handling of the four scale parameters, see the
    Scale topic in the documentation for the image
    window's Scale application (note that the special
    case where the minimum and maximum are both zero
    does not apply to the behavior of BlendColors).
    When you select a new input data set for BlendColors,
    BlendColors will adjust the scaling values to match
    the new input: if the input is a file, the scaling
    will be linear between the minimum and maximum
    values recorded in the file's header; if the input
    is an image window, the scaling will match that used
    for the image window.

color_parameters
    BlendColors has two dialogs to help you assign colors
    to the input wavelengths.  The first, which you can
    open by pressing "color wheel..." in BlendColors'
    main dialog, allows you to select the color for a
    wavelength from a palette.  The color wheel at the
    top of the dialog is the palette.  Position the
    mouse over the desired color in the wheel and press
    the mouse button to select a color.  Your selected
    color, in a range of intensities, will then appear
    in the bar just below the color wheel.  If you are
    satisfied with the color, use the toggle buttons
    below the bar to select the wavelength you want
    to assign to that color and then press the
    "accept color" button.

    The other dialog, which you can open by pressing
    "color parameters..." in BlendColors' main dialog,
    displays your currently selected colors for each
    wavelength.  Just below that display the dialog
    has the RGB components for each color; you can
    edit the component values directly if you want.
    The dialog has three buttons to assist with
    saving the color parameters for use in the future
    or for restoring previously saved parameters:

    save colors to file
        Saves the color parameters as a text file.

    load new colors from file
        Displays a file selection dialog which you
        can use to select a previously saved set of
        color parameters.  The COLORS directory at
        the top level of the Priism distribution has
        some previously generated color parameter
        files.

    set a default color file
        Displays a file selection dialog which you
        can use to select a color parameter file.
        The next time you run BlendColors,
        BlendColors will load those color parameters
        automatically.  BlendColors stores the name
        of the default color file in the blend.select
        file located in the .iveprefs subdirectory
        of your home directory.

method
    BlendColors uses one of three methods to combine
    the scaled intensities for the input wavelengths
    and the assigned colors for those wavelengths to
    generate the blended result.  Let I(j) be the scaled
    intensity (a value between zero and 255) for
    wavelength j at a pixel, C(i,j) be the ith component
    (i.e. the red component for i equal to one) of the
    color assigned to wavelength j, and B(i) be the ith
    component of the blended result for the pixel.  With
    the additive method, the blended color at the pixel
    is the weighted sum of the wavelength colors with
    the scaled intensities at the pixel as the weights:

        B(i) = C(i,1) * I(1) + C(i,2) * I(2) + ...

    With the maximum intensity method, BlendColors
    finds the wavelength, k, which has the brightest
    scaled intensity at the pixel (if there is tie,
    BlendColors uses the wavelength with a lower value
    of k).  The blended color for that pixel is then
    the color for wavelength k times the scaled intensity
    for wavelength k, i.e.

        B(i) = C(i,k) * I(k)

    The priority method treats one of the input
    wavelengths, the lowest priority wavelength,
    differently than the others.  If the lowest priority
    wavelength is k, the blended color at a pixel
    is

        B(i) = C(i,1) * I(1) + ... + C(i,k-1) * I(k-1) +
            C(i,k) * maximum(0, I(k) - I(1) - ... I(k-1) - I(k+1) - ...) +
            C(i,k+1) * I(k + 1) + ...

    In other words, the blended color calculation is
    similar to the additive method but the lowest
    priority wavelength only contributes to the result
    at a pixel if the scaled intensity for the lowest
    priority wavelength at that pixel is greater than
    the sum of the scaled intensities for the other
    wavelengths.

    When BlendColors computes the opacity (B(4) to
    use the same notation as above) for a a pixel,
    the unweighted opacity for each wavelength, i,
    (C(4,i)) is one.

opacity
    When the "opacity" toggle button is on, BlendColors
    generates output with four "wavelengths" rather
    than three.  The fourth "wavelength" records
    how transparent each point is:  information that
    is useful with the progressive rendering option
    of Volume Viewer.

    BlendColors uses the scaled intensity at a pixel
    as a measure of its opacity:  a pixel with a
    scaled intensity of zero is completely transparent
    and a pixel with a scaled intensity of 255 is
    completely opaque.   BlendColors then blends
    opacities in each wavelength just as it blends
    the red, green, and blue components.

priority
    The assignment of the lowest priority wavelength
    only has significance when you select the priority
    method as the method for blending colors.  For
    that method, the contribution of the lowest priority
    wavelength to the blended result at a pixel is
    reduced by the sum of the scaled intensities in the
    other wavelengths, and if the scaled intensity in
    the lowest priority wavelength at a pixel is less
    than the sum of the scaled intensities for the other
    wavelengths, the lowest priority wavelength does
    not contribute to the blended color at that pixel.
    When you use the priority method of blending, select
    the wavelength to use as the lowest priority
    wavelength with the toggle buttons to the right of
    the "lowest" label.

scaling_menu
    If you have BlendColors save the blended images in
    an image window, BlendColors will enable the
    "scaling..." button after you generate the blended
    data.  Pressing the "scaling..." button opens a
    dialog with which you can adjust the scaling
    parameters for the input.  The scaling controls
    in the dialog mimic those in the Image->Scale
    dialog for image windows.  As you adjust the
    scaling, BlendColors will update the currently
    displayed blended section to match the new scaling.
    Once you are satisfied with the scaling, press
    "DoIt" in BlendColors' main dialog to ensure that
    all the sections of the blended result are
    computed with the new scaling parameters.