@database effects.guide

@node Main

            @{fg highlight}MAIN INDEX OF EFFECTS@{fg text}


                @{" AutoCrop   " link AutoCrop}
                @{" Brightness " link Brightness}
                @{" ColorChange " link ColorChange}
                @{" Composite  " link Composite}
                @{" Contrast   " link Contrast}
                @{" Convolute  " link Convolute}
                @{" Extract    " link Extract}
                @{" Flip       " link Flip}
                @{" Gamma      " link Gamma}
                @{" Greyscale  " link Greyscale}
                @{" HistEq     " link HistEq}
                @{" Median     " link Median}
                @{" Negative   " link Negative}
                @{" Noise      " link Noise}
                @{" Resize     " link Resize}
                @{" RIP        " link RIP}
                @{" Rotate     " link Rotate}
                @{" Scale      " link Scale}
                @{" Shift      " link Shift}
                @{" Threshold  " link Threshold}
                @{" Transparency " link Transparency}
                @{" TrueColor  " link TrueColor}


          (*) = Documentation not yet complete
                or out of date.

@endnode

@rem --------------------------------------------------------------

@node AutoCrop "AutoCrop"

@{b}NAME@{ub}
    AutoCrop -- Remove borders from an image

@{b}REXX TEMPLATE@{ub}
    AutoCrop XMARGIN=X/N,YMARGIN=Y/N

@{b}GUI@{ub}
    Use the sliders to set the amount of borders you wish to retain.

@{b}DESCRIPTION@{ub}
    You can use this effect to remove any 'borders' the image may have.
    It scans the image for a constant color border and then removes the
    border.

    You may also set the amount of border pixels  retained  around  the
    image. A value of zero means that no border remains.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    Edit menu/Crop

@endnode

@rem --------------------------------------------------------------

@node Brightness "Brightness"

@{b}NAME@{ub}
    Brightness -- Brightness adjustment

@{b}REXX TEMPLATE@{ub}
    Brightness AMOUNT/N

@{b}GUI@{ub}
    Use the slider to select the change in brightness.

@{b}DESCRIPTION@{ub}
    This changes the general brightness of the image. The  smaller  the
    value is the darker the image becomes. 0 means no change.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"Contrast" link Contrast}

@endnode

@rem --------------------------------------------------------------

@node Composite "Composite"

@{b}NAME@{ub}
    Composite -- composite images.

@{b}REXX TEMPLATE@{ub}
    Composite WITH/A/N,TOP/N,LEFT/N,METHOD/K,RATIO/N

    WITH - the frame id you wish to composite onto this image, ie. the
        source image.

    TOP - the top co-ordinate of the image's top left corner onto this
        image.

    LEFT - the left co-ordinate of the image's top left corner onto
        this image.

    METHOD - This may be any of the following:
        DIRECT
        MINIMUM
        MAXIMUM
        ADD
        SUBTRACT
        MIX
        TRANSPARENT BLACK
        MULTIPLY
        DIVIDE

    RATIO - If METHOD is MIX, then you can use this to select the
        mixing ratio between two images.

@{b}GUI@{ub}
    When you move the mouse into the frame window, you'll  see  a  box,
    which represents the image you are going to composit on this image.
    You can place it onto the image by clicking the left mouse button.

    Choose the methods with the cycle gadgets.

@{b}DESCRIPTION@{ub}
    There are several compositing methods available:

    Direct - the source image values directly replace the values
        in the destination image.

    Minimum - the smaller value from either image is used.

    Maximum - the bigger value form either image is used.

    Add - the values from the images are averaged.

    Subtract - the value from the source image is subtracted  from  the
        value in the destination image.

    Mix - The resulting pixel value is  calculated  as  a  weighted
        average  of  the  source  and destination images so that if Mix
        ratio is 100%, the resulting  pixel  will  be  taken  from  the
        source  image only and if the ratio is 0 %, the resulting pixel
        will be taken from the destination image only. A value of 50  %
        would take an equal amount from each image.

    Transparent Black - If the source image pixel is black, then we'll
        use the destination image value, otherwise the source image.

    Multiply - The source and destination images will be multiplied
        together and the resulting image is scaled to the pixel range.

    Note that you cannot use this effect directly.  You  can  use  only
    either  a  REXX script or drag-and-drop an image from the main list
    into an another image.

    Of course, if the source  image  has  an  alpha  channel,  it  will
    determine  which  parts  of  the image will be transparent. In this
    case I suggest you use the Direct mode.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"Transparency" link Transparency}

@endnode


@rem --------------------------------------------------------------

@node Contrast "Contrast"

@{b}NAME@{ub}
    Contrast -- Contrast correction

@{b}REXX TEMPLATE@{ub}
    Contrast AMOUNT/N

@{b}GUI@{ub}
    Select the amount of correction you wish using the slider gadget.

@{b}DESCRIPTION@{ub}
    The minimum value of correction is -100 and the maximum is +100. At
    the  minimum  value  all  contrast  is lost and all of the image is
    turned dull  grey.  At  the  maximum  value  the  image  becomes  a
    thresholded image for maximum contrast.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"Brightness" link Brightness}

@endnode

@rem --------------------------------------------------------------

@node ColorChange "ColorChange"

@{b}NAME@{ub}
    ColorChange -- Changes a color within a given tolerance.

@{b}REXX TEMPLATE@{ub}
    SRCRED/N/A,SRCGREEN/N/A,SRCBLUE/N/A,DESTRED/N/A,DESTGREEN/N/A,
    DESTBLUE/N/A,TOLERANCE/N

    Default tolerance is zero.

@{b}GUI@{ub}
    On the left side, you see a color chooser for the source  color  and
    on  the  right  side,  you  see  a color chooser for the destination
    color. On the bottom you can set the tolerance.

    If you click on the source image, the color of  the  pixel  that  is
    currently under the mouse pointer will be copied to the source color
    chooser.

@{b}DESCRIPTION@{ub}
    This little effect will change any color to an  another  color.  The
    decision whether a pixel will be changed or not is determined by the
    color-cube distance between the image pixel and the source color. If
    this  distance  is  smaller than or equal to the tolerance, then the
    color is changed.

    If you set the tolerance  level  to  zero,  only  exact  colors  are
    changed.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode


@rem --------------------------------------------------------------

@node Convolute "Convolute"

@{b}NAME@{ub}
    Convolute -- Do a convolution between a mask and the image.

@{b}REXX TEMPLATE@{ub}
    Convolute FILENAME/A

    FILENAME - the convolution to apply.  This file is first searched for
        in the PROGDIR:modules/convolutions subdirectory.

@{b}GUI@{ub}
    On the left side, you'll see a 7x7 matrix, that contains the matrix
    you  wish  to convolute the image with. Below it, you can enter the
    bias and the divisor.

    The right side of the window contains several buttons. You can load
    or   save  the  current  convolution  matrix  by  clicking  on  the
    respective  buttons.  "Clear"  will  reset  the  matrix.  Click  on
    "Convolute!", when you are done setting your convolution matrix.

    There's also a menu  that  contains  also  the  commands  that  are
    available as buttons. There are also some nice presets.

@{b}DESCRIPTION@{ub}
    Convolutions are a bit tricky subject.  You  can  probably  find  a
    great  deal  of information from any good book that discusses image
    processing in detail. I'll try to run a short explanation here:

    A convolution matrix is a matrix that is laid on top of a pixel and
    each  value  around it is multiplied by the corresponding weight in
    the matrix. Then they're all summed together. For  example  if  the
    (3x3) convolution matrix is:

    0 1 0

    1 2 1

    0 1 0

    and  the  pixel  values  in  the  same  neighbourhood  are   (we're
    processing pixel valued '8'):

    5 5 9

    4 8 3

    0 3 0

    The resulting image would be:

    5 * 0 + 5 * 1 + 9 * 0
              +
    4 * 1 + 8 * 2 + 3 * 1
              +
    0 * 0 + 3 * 1 + 0 * 0  = 0+5+0+4+16+3+0+3+0 = 31.  So, the result
    pixel is 31 and so we change the 8 to 31 and move on to the next
    pixel.

    What's the point? Well, the theory is a bit complicated to get into
    here,  but  basically  you  can  do  low-  and high-pass filtering,
    gradient calculation and lots of other cool stuff with this.

    Oh, one more thing: Since you can use only  whole  numbers  in  the
    matrices  (floating  point  is such a hassle) you need to provide a
    divisor. The resulting  pixel  is  divided  by  the  value  of  the
    divisor,  so that the resulting pixel value is better scaled within
    the limits of the pixel (that is, between 0 and 255). Normally, you
    should use the value of 1. Aw hell, look at the examples provided.

    Bias: The bias value is added to the pixel value after applying the
    divisor.  The point is to make some operations (like some high-pass
    filters) to give a bit brighter image. You can also use a  negative
    value.

    BTW, take a look at the menus - you'll get some  nice  presets  for
    different types of filters.

    Loading and saving: Well, not much to say. You can make,  save  and
    load  your  own convolution matrices. This module defaults to using
    the modules/convolutions -directory for it's files.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode

@rem --------------------------------------------------------------

@node Extract "Extract"

@{b}NAME@{ub}
    Extract -- extract color information.

@{b}REXX TEMPLATE@{ub}
    Extract RED/S, GREEN/S, BLUE/S, ALPHA/S

@{b}GUI@{ub}
    Use the checkboxes to select the color components.

@{b}DESCRIPTION@{ub}
    This simple effect will keep those color components you specify  in
    the image and discard all the rest.

    Naturally, the resulting image will be black if you discard all  of
    the components.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode

@rem --------------------------------------------------------------

@node Flip "Flip"

@{b}NAME@{ub}
    Flip -- flip an image.

@{b}REXX TEMPLATE@{ub}
    Flip X/S,Y/S

@{b}GUI@{ub}
    You may select which way to flip the image. X - as  usual  -  means
    horizontal and Y vertical direction.

@{b}DESCRIPTION@{ub}
    Flip the image.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode


@rem --------------------------------------------------------------

@node Gamma "Gamma Correction"

@{b}NAME@{ub}
    Gamma -- Provide a gamma correction feature.

@{b}REXX TEMPLATE@{ub}
    Gamma AMOUNT/N/A

    AMOUNT should be gamma * 100.

@{b}GUI@{ub}
    Enter the gamma value using the slider. The  gamma  correction  you
    give  will  be divided by 100 before being applied (that is, 100 on
    the slider means a gamma correction of 1; 222 on the slider means a
    gamma correction of 2.22 and so on).

@{b}DESCRIPTION@{ub}
    Due to the unlinear nature of display devices, a  gamma  correction
    must  be  used.  Most of the time this is done automatically by the
    display device, but occasionally  you'll  meet  images  that  could
    benefit from additional gamma corretion.

    Gamma is usually defined as

              g
        F := A

    where F = new value, A =  old  value  and  g  =  gamma  correction.
    Obviously,  gamma  is a real (floating point) number and a value of
    1.0 means no correction at all.

    Basically, if you wish your image to  be  brighter,  give  a  gamma
    correction  over  1.  If  you  wish  to  darken  it,  give  a gamma
    correction of <1.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"Brightness" link Brightness}, @{"Contrast" link Contrast}.

@endnode

@rem --------------------------------------------------------------

@node Greyscale "Greyscale"

@{b}NAME@{ub}
    Greyscale -- strip color information from the image.

@{b}REXX TEMPLATE@{ub}
    Greyscale

@{b}GUI@{ub}
    None.

@{b}DESCRIPTION@{ub}
    This will strip the color information from the given area.

    If the whole image is selected, then the image  format  is  changed
    into greyscale as well.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"TrueColor" link TrueColor}

@endnode

@rem --------------------------------------------------------------

@node HistEq "Histogram Equalization"

@{b}NAME@{ub}
    HistEq -- Perform histogram equalization

@{b}REXX TEMPLATE@{ub}
    HistEq LOCALRADIUS/N

@{b}GUI@{ub}
    Use the cycle gadget to select whether you wish to have a local  or
    a  global  equalization.  If you choose local, then you can use the
    slider to select the radius.

@{b}DESCRIPTION@{ub}
    This equalizes the histograms in the given area of the image, which
    usually  improves  the  image  contrast.  However,  the colors will
    suffer from this.

    For a description of  the  algorithm,  see  any  good  textbook  on
    digital image processing.

    Note that the local histogram equalization is quite slow, since for
    it  to  be  effective,  you  will need to set the radius to a quite
    large  number.  Radius  in  this  case  refers  to   a   Radius*2+1
    neighbourhood  area,  ie  selecting  a  radius of 16 means that the
    local equalization will be done using a 33*33 local neighbourhood.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode

@rem --------------------------------------------------------------

@node Median "Median"

@{b}NAME@{ub}
    Median -- Do a median filter on the selected area.

@{b}REXX TEMPLATE@{ub}
    Median RADIUS/N/A

@{b}GUI@{ub}
    Use the slider to select the radius you wish to use for the median
    filtering.

@{b}DESCRIPTION@{ub}
    The idea of median filtering is to take  an  environment  around  a
    pixel and then sort the values. The middle value (also known as the
    median) is then selected to represent this pixel. For  example,  if
    we  use  a  3x3  matrix  (ie  radius  = 1) and we look at the pixel
    surroundings we see:

        3    5   78
        7    8    9
        0    2    1

    We'll now sort these values and get : 0, 1, 2, 3, 5, 7, 8,  9,  78.
    It  can  be easily seen that the middle value is 5. As you can see,
    the anomalous value  of  78  was  filtered  out.  Median  filtering
    removes strong 'spikes' quite well.

    This method is quite good at removing noise and  speckles  from  an
    image, but it will cause some blurring of edges.

    Currently, this method can use a maximum radius of 5 pixels to each
    direction (which makes the filtering matrix 11x11 pixels in size).

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"Noise" link Noise}

@endnode

@rem --------------------------------------------------------------

@node Negative "Negative"

@{b}NAME@{ub}
    Negative -- make a negative out of the current area

@{b}REXX TEMPLATE@{ub}
    Negative

@{b}GUI@{ub}
    None

@{b}DESCRIPTION@{ub}
    Make a negative out of currently selected area.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode

@rem --------------------------------------------------------------

@node Noise "Noise"

@{b}NAME@{ub}
    Noise -- Add noise to the image.

@{b}REXX TEMPLATE@{ub}
    Noise AMOUNT/N/A,FREQUENCY=FREQ/N,TYPE/K

    Values are given in percents.
    Type may be either "ADDITIVE" or "MULTIPLIKATIVE".

@{b}GUI@{ub}
    Use the sliders to determine the amount of noise in percent and
    the frequency in percents.

@{b}DESCRIPTION@{ub}
    Additive noise is generated by adding a random value to  the  pixel
    value and then clamping it to the pixel range. This produces a flat
    distribution of noise to the image.

    Multiplikative noise is generated by multiplying the  random  value
    with the pixel value and then scaling it to the pixel value range.

    The noise amounts are given in percents of the full  dynamic  range
    of the pixel.

    Frequency gives the probability for a  given  pixel  that  it  gets
    noise  applied.  For example, a value of 50 means that every second
    pixel (on the average) will get noise  added/multiplied  to  it.  A
    value of 100 gives noise on every pixel.

@{b}BUGS@{ub}
    Should really support also Gaussian noise.
    The user should be able to set if he/she wants to clamp or rescale
    the values...

@{b}SEE ALSO@{ub}
    @{"Median" link Median"}

@endnode

@rem --------------------------------------------------------------

@node Resize "Resize"

@{b}NAME@{ub}
    Resize -- Enlarges an image by adding black borders around it.

@{b}REXX TEMPLATE@{ub}
    Resize NEWHEIGHT=NH/N/A,NEWWIDHT=NW/N/A

    Arguments are in pixels.

@{b}GUI@{ub}
    Use the sliders to select the size.

@{b}DESCRIPTION@{ub}
    Resizes the image canvas by adding black borders to the image.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode

@rem --------------------------------------------------------------

@node RIP "Remove Isolated Pixels"

@{b}NAME@{ub}
    RIP - Removes pixels with no neighbours.

@{b}REXX TEMPLATE@{ub}
    "Remove Isolated Pixels"

@{b}GUI@{ub}
    None.

@{b}DESCRIPTION@{ub}
    This removes all those pixels from an image whose surroundings
    consist of a single color only.

@{b}BUGS@{ub}
    Should really support a tolerance limit for the color.

@{b}SEE ALSO@{ub}

@endnode

@rem --------------------------------------------------------------

@node Rotate "Rotate"

@{b}NAME@{ub}
    Rotate -- rotates an image freely.

@{b}REXX TEMPLATE@{ub}
    Rotate ANGLE/N/A, ANTIALIAS/S

    ANGLE must be between -90 and 90 degrees.

@{b}GUI@{ub}
    Select the angle using the slider.

@{b}DESCRIPTION@{ub}
    You can use this to rotate the image from -90 to  90  degrees.  The
    remaining area is filled with black.

    Negative angle values  mean  clockwise  and  positive  values  mean
    counterclockwise.  (If you know your trigonometry well, this should
    be obvious ;-)

    If you specify antialiasing, then the  resulting  image  will  look
    better, but it will take longer to generate.

@{b}BUGS@{ub}
    Should really use the background pixel value instead of black to
    fill the voids.
    Currently does not work for ARGB images.

@{b}SEE ALSO@{ub}

@endnode

@rem --------------------------------------------------------------

@node Scale "Scale"

@{b}NAME@{ub}
    Scale -- Change the size of the image

@{b}REXX TEMPLATE@{ub}
    Scale NW=NEWWIDTH/N,NH=NEWHEIGHT/N,MODE/K,PERCENT/S

    Arguments are in pixels, unless the PERCENT  switch  is  given,  in
    which  case  they're  interpreted  as a percentage value of the old
    size.

@{b}GUI@{ub}
    You may control the new size of  the  image  by  using  the  slider
    gadgets. You can choose the units you desire with the cycle gadgets
    to the right of the dialog box.

    If you wish that the aspect ratio of the image is not changed  when
    you fiddle with the sliders, check the 'Lock Aspect Ratio' checkbox
    and the height and width will be automatically updated.

    The cycle gadget below tells the method you are going to  use  (see
    below).

@{b}DESCRIPTION@{ub}
    This scales an image using either a Quick method (fast, but  blocky
    result)  or  a  Color  Average method, which is slower but produces
    better results.

    The MODE argument from REXX can be either "QUICK" or  "AVERAGE"  to
    signify which method you wish to use.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode

@rem --------------------------------------------------------------

@node Shift "Shift"

@{b}NAME@{ub}
    Shift -- Shifts pixels around in the image.

@{b}REXX TEMPLATE@{ub}
    Shift X/N,Y/N

    X and Y should be signed integers.

@{b}GUI@{ub}
    Use the sliders to select the amount you wish to shift the image.

@{b}DESCRIPTION@{ub}
    Basically moves image to the direction you wish. The space that  is
    revealed is filled with black.

    Negative X values mean left, positive mean right. Negative Y values
    mean up and positive mean down.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode

@rem --------------------------------------------------------------

@node Threshold "Threshold"

@{b}NAME@{ub}
    Threshold -- threshold an image

@{b}REXX TEMPLATE@{ub}
    Threshold LIMIT/N/A,INTENSITY/S

    LIMIT must be between 0..255, if the image is a standard RGB or
    Graylevel image.

    INTENSITY, if specified, sets the threshold to intensity instead
    of using separate channels.

@{b}GUI@{ub}
    Use the slider to set the thresholding limit.  Whether you wish to
    use intensity or per-channel thresholding can be controlled with
    the checkbox.

@{b}DESCRIPTION@{ub}
    This will turn an image into a bicolor image by setting each  value
    that  is  lower  than the threshold to black and each value that is
    higher than the threshold to white. Values that are  equal  to  the
    threshold are set to white.

    However, note that the thresholding is done on a channel-per-channel
    basis, unless you set intensity to true, so if you apply this effect
    to an RGB image, then you'll get an 8-color image!

    If INTENSITY has been set, then this will always produce  a  bicolor
    image.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode

@rem --------------------------------------------------------------

@node Transparency "Transparency"

@{b}NAME@{ub}
    Transparency -- Manage transparency on an image.

@{b}REXX TEMPLATE@{ub}

    Transparency R=RED/N/A,G=GREEN/N/A,B=BLUE/N/A,TRANS/N/A,BACKGROUND/S

    RED, GREEN and BLUE determine the color that should be
        transparent.

    TRANS is an unsigned integer between 0 and 255 that will
        be the new transparency value for this image and color.

    BACKGROUND overrids R, G and B, and selects the color based
        on a guess of the image's background color.

@{b}GUI@{ub}

    Use the slider  gadgets  to  select  a  color  that  will  be  made
    transparent.  The  transparency  value  (0  =  solid,  255  = fully
    transparent) can be determined with the slider below.

    If you have colorwheel.gadget and  gradientslider.gadget  installed
    you'll  also  get  one of each to help you in determining the color
    value. These gadgets are standard in OS 3.0 (V39) onwards.

    Use the settings in the Presets - menu to select a  suitable  color
    default (White, black or background color).

    You can also click on the image  and  the  color  under  the  mouse
    pointer is then copied into the sliders and colorwheel.

@{b}DESCRIPTION@{ub}

    This tool will enable you to set a transparent color in the  image.
    It will convert the image into ARGB - colorspace, if needed.

    If you ask for a background color, you should realize  that  it  is
    calculated  currently  as  an  average  of all corner pixels in the
    image. If your image does not have  a  clear  background,  this  is
    likely to be wrong...

    Note that if you change the image after this, your  selections  may
    not  be  correct anymore: for example, a rotate effect may add more
    black pixels to the image, but these will not necessarily be marked
    as transparent.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode
@rem --------------------------------------------------------------

@node TrueColor "TrueColor"

@{b}NAME@{ub}
    TrueColor -- Change the image into TrueColor

@{b}REXX TEMPLATE@{ub}
    TrueColor

@{b}GUI@{ub}
    None.

@{b}DESCRIPTION@{ub}

    This is the opposite of the  Greyscale  effect.  It  transforms  an
    image  from  the  Grayscale  format  (8 bit) to full RGB format (24
    bit). It does not really change any image information.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{ "Greyscale" link Greyscale}

@endnode

@rem --------------------------------------------------------------

@node

@{b}NAME@{ub}

@{b}REXX TEMPLATE@{ub}

@{b}GUI@{ub}

@{b}DESCRIPTION@{ub}

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode

@rem --------------------------------------------------------------