RISC DISC 2/RISC_DISC_2.iso/pd_share/program/sprtools/docs/spr_fsi

Text File | 1995-03-10 | 12.9 KB | 327 lines

spr_fsi
=======

Version 1.10 (20-Apr-1994)
SPRtools block 1c release.
(C) 1993-4 DEEJ Technology PLC

Features
--------
Sprite processing tools, features provided;

        Increase / Decrease bits per pixel (number of colours),
        Floyd Steinburg Integer dithering,
        Image scaling with true sub-sampling (anti-aliasing) and interpolation,
        Dynamic intensity range expansion,
        Gamma correction,
        Image inversion,
        Filters including smoothing, sharpening, noise removal & user defined
        Support for common fixed palettes,
        Palette optimisation,

Restrictions
------------
Enough memory must be available to hold the source image and two lines of
the destination image. Further memory is required by certain operations
such as filtering. Palette optimisation can require a large amount of memory
for images with thousands of colours.

Only the first sprite in the file is recognised.

Syntax
------
spr_fsi [-bpp <bpp>]
    [-scale <scale>]
    [-palette <palette>]
    [-invert]
    [-expand]
    [-gamma <gamma>]
    [-filter <filter>]
    [-aspect]
    [-nodither]
    [-nointerp]
    [-quiet]
    [-help]
    [-in <input sprite file>]
    [-out <output sprite file>]
    [-err <progress/error file>]

Options may be abrieviated to the minimum unique form.
All options and parameters are case specific.

Files default to stdin and stdout with progress or errors to stderr.

-bpp <bpp>
<bpp>    = {1 | 2 | 4 | 8 | 15 | 24 }

        Bits per pixels in the output image. The default is 24.
        The 24 bpp option produces the standard 24/32 bit deep sprite
        format, a (non-standard) true 24 format is also available,
        which is described later.

-scale <scale>
<scale> = {<xsize> ,<Ysize> |
       <XYmul>:<XYdiv> |
       <Xmul>:<Xdiv>,<Ymul>:<Ydiv> }

        The amount the scale the output image can be specified in
        three ways.

        <Xsize>,<Ysize> scales to an absolute size
        e.g. -scale 1280,1024 for a sprite 1280x1024 pixels

        <XYmul>:<XYdiv> scales both axis by the same ratio
        e.g. -scale 3:2 to expand by 3/2 (1.5)

        <Xmul>:<Xdiv>,<Ymul>:<Ydiv> scales each axis separately
        e.g. -scale 3:2,1:2 to expand horizontally by 3/2
                                and reduce vertically by 1/2

        Scales which would produce a very small output sprite, or
        equate to an expansion of more than 128x in any direction are
        prevented. The scale defaults to 1:1 in each direction, unless
        the input image has rectangular pixels and the -aspect flag is
        not set, in this case a scale of 1:1,2:1 is used to covert the
        sprite to use square pixels.

-palette <palette>
<palette> = {rgb | grey | desktop | win3 | fix | opt }

        Selects the palette type for output sprites with 1-8 bpp.
        The palette defaults to the same as the input sprite.
        If the input sprite does not have a palette, the default for
        a RISC OS mode with the same bpp is used. Certain palette
        types may only be used for some numbers of bits per pixel in
        the output sprite.

        The ‘rgb’ palette can be used with bpp 4 and 8. In 4 bpp the
        palette gives 9 grey levels, 6 fully saturated colours and
        orange, in a layout designed to be desktop friendly. In 8 bpp
        the palette gives 46 grey levels plus a 6x6x6 level RGB colour
        cube (combinations of 6 levels for each component).

        The ‘grey’ palette gives linear grey scales for bpp 1-8,
        giving 2 to 256 grey levels.

        The ‘desktop’ palette gives the standard 16 colour RISC OS
        desktop palette in 4 bpp, and the standard VIDC1 256 colour
        mode palette in 8 bpp.

        The ‘win3’ palette gives a Windows 3 palette in 4 bpp,
        consisting of 4 grey levels, 6 fully saturated colours and
        6 half brightness colours. In 8 bpp a custom (non-Windows)
        palette with 176 grey levels, a 4x4x4 level colour cube plus
        18 RGYBMC shades is used.

        The ‘fix’ palette will use the input sprites palette (or the
        default) but will convert old type 12 bit palettes stored in
        the sprite to full 24 bit. e.g. &B0G0R0xx to &BBGGRRxx

        The ‘opt’ palette will examine the input sprite after all
        pre-processing operations have been performed, and will choose
        the best combination of colours to use in the output image.
        More details on this process are given below. This option
        can only be used for output sprites of 4 or 8 bpp.

-invert        Invert the source image before processing.

-expand        Expand the dynamic range the source image before processing.
        Expand works by finding the lowest and highest intensity pixels
        in the image, the colours of all pixels in the image are then
        adjusted so that the intensities range from zero to maximum.

-gamma <gamma>
<gamma>    = positive floating point number

        Gamma correction can be performed on the source image before
        processing. The default value is 1.0 which has no effect.
        Values >1.0 (2.2 is the recognised standard) are used to move
        the contrast detail in the image to the brighter part of the
        intensity range. This use useful for correcting scanned images
        and for preparing sprites for printing. Values less than 1.0
        can be used to move detail to darker intensities.

-filter <filter>
<filter> = {filter> | <user filter> }

        Filters can be used to perform a variety of image processing
        on the image before further processing. See later for a
        description of how filtering works.

<standard filter> = filter name:-
        sharpen1 - Sharpen week
        sharpen2 - Sharpen medium
        sharpen3 - Sharpen strong
        smooth1  - Smooth week
        smooth2  - Smooth medium
        smooth3  - Smooth strong
        average  - Averages with surrounding pixels
        noise1   - Noise removal week
        noise2   - Noise removal medium
        noise3   - Noise removal strong
        edge     - Horizontal and vertical edge extraction
        edgeV    - Vertical edge extraction
        edgeH    - Horizontal edge extraction
        edgeNW   - Edge extraction along a 45 degree angle
        edgeNE   - Edge extraction along a 45 degree angle
        edgeSW   - Edge extraction along a 45 degree angle
        edgeSE   - Edge extraction along a 45 degree angle
        emboss1  - 3D embossing effect
        emboss2  - 3D embossing effect, inverted

<user filter> = <a>,<b>,<c>,<d>,<e>,<f>,<g>,<h>,[<mul>,[<div>,[<add>,[<diff>]]]]
        Where <a> to <h> are the rows and columns of the 3x3 filter
        matrix. <mul> and <div> are the summation scaling factors which
        default to 1. <add> is an optional component to be added after
        scaling. <diff> is the optional noise filtering level.
        All numbers are positive or negative integers except <div> and
        <diff> which must be positive.

-aspect        Normally all sprites containing rectangular pixels are
converted
        to square pixels during processing (doubling the Y resolution),
        if the -aspect flag is given a rectangular pixel input sprite
        will give a rectangular pixel output sprite.

-nodither    This option can be used to prevent Floyd Steinburg Integer
        dithering from being used during processing. This will speed
        up processing but will result in a poor quality output. It
        has no effect when the output sprite is 24 bpp.

-nointerp    This option prevents pixel area summing or interpolation being
        used when scaling the image (see the section below on scaling).
        This will speed up the scaling of images, but with a reduction
        in quality. It can be used when scaling up an image to prevent
        the loss of sharpness caused by interpolation.

-quiet        Prevents the printing of the state of options on stderr during
        processing.  Progress and errors are still output.

-help        Prints a syntax summary.


Info
----
True 24 bit sprite format:
        spr_fsi normally produces standard RISC OS deep sprite 24/32
        bpp format when using -bpp 24, this format is 25% larger than
        other 24 bit formats and does not compress as well.

        By using ‘-bpp 8 -palette rgb’ a non standard true 24 bit deep
        sprite can be produced. It will not be understood by RISC OS
        applications, but can be used as a storage format for sprites
        to be used again with spr_fsi.

        The format has a sprite mode specifier of type 8 (currently
        unassigned in RISC OS 3.5) and stores pixels as consecutive
        three byte quantities (blue, green and red bytes) padded to
        the next word boundary at the end of each line.

Scaling        spr_fsi uses two techniques to improve the scaling of images.
        The first is used when scaling down an image, where each output
        pixel will depend on many pixels in the input. An area of the
        source image corresponding to a pixel in the destination image
        is summed to give an average colour. This achieves the effect
        of anti-aliasing which reduces loss of detail due to scaling
        down.

        When scaling up a pixel in the input is converted to many
        pixels in the output. To prevent a blocky image pixels are
        interpolated to achieve a smooth graduation between them,
        rather than sharp boundary. This produces a much smoother
        image at the expense of some sharpness (the image can be
        pre-sharpend first using a filter).

        If the image is being scaled up in one direction and reduced
        in another the two techniques are used together. Anti-aliasing
        and interpolation may be turned off using -nointerp.

Optimised palette
        When reducing the number of bits per pixel of an image the
        various fixed palette types can be chosen to represent colours
        which will be close to the original. Most fixed palettes aim
        to cover the colour cube by providing shades which have
        combinations red, green and blue ranging from zero to maximum.

        These fixed palettes work well for images which have a large
        range of colours spanning the colour cube, but where an image
        has for example, a large number of green shades, a few reds
        and no blues, many colours in the fixed palette will not be
        used, and the green shades will be reduced to a far few
        number in the output. In this case a palette with more green
        shades and no blue would be more appropriate.

        When reducing images down to 8 (or 4) bpp the -palette opt
        option will cause the input sprite to be analysed and the
        256 (or 16) colours which will give the best possible match
        to the original image chosen, and used in the output images
        palette.

        After any pre-processing operations have been performed, a
        histogram of all the colours used in the input image is
        built. The histogram is then filtered to remove colours which
        are only used a few times to reduce the amount of calculation.
        The remaining colours are picked out so as to reduce the
        difference between the source and destination images as much
        as possible. This is calculated by the amount of use of the
        colour and how close similar colours are to it.

        Usually the optimised palette will generate an image which
        is much closer to the original, with dithering greatly reduced.
        For some images however, the results may not be as pleasing
        as one of the fixed palettes. Experimentation may be necessary.

Filters        Filters work by taking a pixel and modifying its value
        depending on the 8 surrounding pixels. The filter consists of
        a 3 by 3 matrix, the center corresponding to the current pixel.
        The values in the matrix are used to multiply the value of the
        pixel under it, values may be positive or negative

        e.g. 1 2 1    The center pixel is multiplied by 4, its
             2 4 2    neighbours horizontally an vertically are
             1 2 1    multiplied by 2, and its diagonals by 1.

        The sum of the nine pixels multiplied by the matrix elements
        is multiplied and divided by scaling factors to reduce its
        range back to the valid values for a pixel. In the above
        example the sum comes to 16x, so it must be divided by 16.

        Another value may be added to the sum to brighten the pixel
        (+ve) or darken it (-ve).

        Finally a differencing filter value can be given. If the
        difference between the original pixel and the result of the
        above process is greater than the difference value the pixel
        is unchanged, other wise it is replaced with the filtered
        value. If no difference is given the pixel is always replaced.

        Filters work on each colour component separately and can
        produce colour changes, e.g. the edge extracting filter.
        Filters work on the input image and can only use the closest
        colours in the input image to represent the desired filter
        values. It is recommended that filter is done with as many
        bits per pixel as possible. e.g. if an 8 bpp image is going
        to be filtered to and increased to 24bpp, the increase depth
        is done first, followed by another run to do the filtering.

Processing      The main processing done by spr_fsi is the scaling and the
        change in colour depth which are done at the same time.
        Other pre-processing options are performed before this
        in the following order.

        filter            (modifies input image in memory)
        invert            (modifies palette only if image <= 8bpp)
        expand            (modifies palette only if image <= 8bpp)
        gamma            (modifies palette only if image <= 8bpp)
        optimise palette    (only effects output image)

        Certain operations such as filtering should be done with the
        maximum bpp, and others may give better results if done after
        scaling. Two (or more) runs of spr_fsi can be performed to
        achieve the best results.


See also spr_info.

!ComndCTRL configuration file: spr_fsi