"

 COPYRIGHT (c) 1991 by Claus Gittinger

              All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

"{ Package: 'stx:libview' }"

"{ NameSpace: Smalltalk }"

Object subclass:#Image

	instanceVariableNames:'pixelFunction bytes width height bitsPerPixel depth colorMap

		maxPixelValue rowByteSize bitsPerSample samplesPerPixel

		photometric device deviceForm monoDeviceForm fullColorDeviceForm

		mask maskedPixelsAre0 fileName imageSequence metaData'

	classVariableNames:'BadImageFormatQuerySignal CannotRepresentImageSignal

		CollectGarbageWhenRunningOutOfColors DitherAlgorithm

		FileCreationErrorSignal ImageErrorSignal ImageLoadErrorSignal

		ImageNotFoundQuerySignal ImageSaveErrorSignal

		InformationLostQuerySignal Lobby NumberOfDitherColors

		UnrepresentableColorSignal'

	poolDictionaries:''

	category:'Graphics-Images'

!

!Image class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1991 by Claus Gittinger

              All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    this class provides representation for all kinds of images

    (monochrome, greyscale and color) and may finally replace Form.

    Depths of 1, 2, 4, 8, 16, 24 and 32 are supported.

    An Image keeps all of its information in a device independent way,

    but may be associated to a device (i.e. getting a device-specific version of it).

    The data held keeps all information which was originally present,

    even if the display-device has lower resolution.

    Therefore, it is possible to process and manipulate images without loosing

    color information.

    Images may be created manually (by providing a pixel array),

    by screen capture, by reading a file (using an ImageReader) or

    dynamically computed by a pixelFunction (functional image).

    This gives you a device independent image.

    For display, a device representation is required, which can be

    acquired by sending the 'onDevice:aDevice' message to the image.

    This creates a (possibly dithered) device-form,

    representing the image using the currently available colors.

    In rare cases, an explicit monochrome representation of the image is needed

    (some older X servers take monochrome icons only), this can be created by sending

    it the message

        'monochromeOn:aDevice'.

    As this class is very old and originated at times when typical graphic diplays only

    supported a limited number of colors (16 or 256), or where even monochrome b&w or grayscale 

    (NeXTCube or 4-plane NeXTStation).

    You will find a lot of code which deals with color allocation optimizations and dithering. 

    Nowadays, these are hardly ever needed, and most of the time, 

    images will be converted to 24bit truecolor (8x8x8) when converted to a device representation.

    (see examples_dithering for this old code in action)

    An image's pixel interpretation is controlled by the photometric instance variable

    and (if that is #palette) a colorMap.

    This is in contrast to the ST-80 way, where all of this info is in the colorMap

    (and using specialized colorMaps for b&w / greyScale images).

    This may change in future versions for more application compatibility.

    To convert pictures from/to external file-formats, image readers are used

    which have the file-format knowledge built in.

    There are readers for most common formats available

    (see ImageReader and especially subclasses such as TIFFReader, GIFReader etc.).

    File formats are handled by subclasses of ImageReader, which understand

    a specific format. You can add more readers, by adding an association

    to the mapping maintained in the MIMETypes class.

    (see the MIMETypes>>initialize and possibly the display.rc file, where this is done).

    Some algorithms used here (especially dithering & color allocation) are

    experimental and far from being perfect (some are very slow).

    For now, the most common cases have been optimized and perform reasonably

    fast - however, with uncommon depth/visualType combinations, you may

    run into very slow fallback methods. If this leads to problems, you may have to

    write a specially tuned (inline-C) version for that case.

    The pixelFunction enables dynamically computed functional images: instead of

    providing a byteArray containing pixel data, a function is used which maps

    x/y coordinates to a pixel value (see examples).

    For display, the bits array is used internally and filled by the function.

    Much more work is needed if you plan to do heavy image processing and will

    (may) be done in the future if there is a demand for it ...

    Dithering (read sectin above) can be controlled by the DitherAlgorithm classVariable:

       DitherAlgorithm:

       nil                  a simple threshold algorithm

                            (i.e. for mono, p<0.5 -> black, p>=0.5 -> white)

       #pattern             patterned dither

                            (for p, take dithered color to fill pixel;

                             uses dithering in color-class)

       #error               error diffusion dither (Floyd-Steinberg)

                            planned - not yet implemented.

    Notice:

        the set of attributes and the way they are stored originated initially

        from the need to represent tiff images. 

        These turned out to use a relatively large set of atributes, 

        of which many are unused in other image formats. (so it was sufficient).

        Later, some VisualWorks compatibility protocol was added (mapped palettes, for

        example), and some stuff could well be redefined in simpler ways.

        We may do that, if we are bored and there is nothing else to improve... ;-)

    [instance variables:]

        width               <Integer>       the width in pixels

        height              <Integer>       the height in pixels

        bytes               <ByteArray>     the full image information

        photometric         <Symbol>        #rgb, #palette, #blackIs0 or #whiteIs0

        samplesPerPixel     <Integer>       the number of planes

        bitsPerSample       <Array>         the number of bits per plane

        colorMap            <Array>         only if photometric is #palette;

                                            maps pixel values to r/g/b values.

        device              <Workstation>   the device on which deviceForm,

                                            monoDeviceForm and lowResDeviceForm are

        deviceForm          <Form>          the device form which gives the best

                                            possible approximation of the image on

                                            device using standard colors.

        monoDeviceForm      <Form>          the device form which gives a monochrome

                                            aproximation of the image on device.

        fullColorDeviceForm <Form>          the device form which gives the best

                                            possible aproximation of the image on

                                            device using private colors.

                                            (not yet implemented)

        mask                <ImageMask>     an optional mask;

                                            if non-nil, only pixels for which the

                                            corresponding mask bit is non-zero

                                            are drawn.

        maskedPixelsAre0    <Boolean>       a hint for image processors and drawers

                                            if true, masked pixels are known to be

                                            zero in the pixel bytes.

        fileName            <String>        the name of the file from which the

                                            image was loaded - nil otherwise.

                                            Useful for image save functions

                                            and for the UIPainter utility.

        imageSequence                       the imageSequence, of which the

                                            instance is a frame or nil,

                                            if it's not part of a sequence.

        bitsPerPixel                        obsolete - not used in ST/X (kept for a while for subclasses)

        depth                               - these have been added in instVar-slots

        maxPixelValue                       - according to the ST-80's image class.

        rowByteSize                         - to allow loading of st-80 images

                                            - (which are stored as instVarAt:put: expressions)

    [class variables:]

        Lobby               <Registry>      keeps track of known images

                                            (for resource freeing with garbage collector)

        DitherAlgorithm     <Symbol>        defines how to dither

        NumberOfDitherColors <Integer>      defines, how many dither colors to use

        FileFormats         <Dictionary>    associates filename extensions to

                                            image reader classes (now set-up in startup-file)

        CollectGarbageWhenRunningOutOfColors

                            <Boolean>       if true, and we run out of available

                                            device colors during creation of a

                                            device image, collect garbage for

                                            possible image reclamation.

                                            If false, proceed immediately.

                                            Default is true.

        ImageNotFoundQuerySignal

                            <QuerySignal>   raised, if an image could not be loaded

                                            from a file. The parameter is the images

                                            fileName.

                                            A handler may return a replacement

                                            image or proceed with nil.

                                            If unhandled, a nil is returned from the

                                            image creation.

        BadImageFormatQuerySignal

                            <QuerySignal>   raised, if an image could not be loaded

                                            from a file due to a file error or

                                            unsupported format.

                                            A handler may return a replacement

                                            image or proceed with nil.

                                            If unhandled, a nil is returned from the

                                            image creation.

        ImageSaveErrorSignal

                            <Signal>        parent of errors below.

        FileCreationErrorSignal

                            <Signal>        file could not be created when saving an

                                            image.

        CannotRepresentImageSignal

                            <Signal>        the specified ImageReader cannot represent

                                            the given image.

        InformationLostQuerySignal

                            <Signal>        the specified ImageReader can represent

                                            the given image, but some information

                                            (typically color resolution) is lost.

                                            If unhandled, the save proceeds as usual.

    caveat:

        the information in

            photometric, bitsPerPixel, bitsPerSample, samplesPerPixel, depth , colorMap and maxPixelValue

        is partially redundant and its handling stupid (not to say: braindamaged ;-).

        The only excuse is that it grew over time, had to incorporate various alien/older schemes for

        compatibility reasons (mostly coming from tiff format, which was the very first supported format).

        All of the above belongs into the single colorMap which must migrate from

        a stupid seqColl to a color-aware real colorMap.

        (we are in the process of doing so...)

    todo:

        support alpha masks

        cleanup the dithering & conversion code

        cleanup the color/photometric mess

    [See also:]

        Form Icon ImageReader

    [author:]

        Claus Gittinger

"

!

examples

"

    reading from a file (many formats are supported):

    (notice that the bitmaps directory is searched for along

     the system path - therefore, you may add your own bitmap

     directory to the beginning of the path and thus override

     any default bitmaps, or make certain that your application

     finds its bitmaps - even if they are in a separate directory)

                                                                                        [exBegin]

        (Image fromFile:'../../goodies/bitmaps/gifImages/garfield.gif') inspect

                                                                                        [exEnd]

    Boy, was I young, when writing ST/X... ;-)                                                                                                 

                                                                                        [exBegin]

        (Image fromFile:'../../goodies/bitmaps/gifImages/claus.gif') inspect

        ((Image fromFile:'../../goodies/bitmaps/gifImages/claus.gif') rotated:90) inspect

        ((Image fromFile:'../../goodies/bitmaps/gifImages/claus.gif') rotated:45) inspect

        ((Image fromFile:'../../goodies/bitmaps/gifImages/claus.gif') rotated:25) inspect

                                                                                        [exEnd]

    better use package relative file names:

                                                                                        [exBegin]

        (Image fromFile:'bitmaps/gifImages/garfield.gif' inPackage:'stx:goodies') inspect

                                                                                        [exEnd]

    various file formats are supported:

                                                                                        [exBegin]

        (Image fromFile:'bitmaps/xpmBitmaps/misc_icons/SmalltalkX_clr.xpm' inPackage:'stx:goodies') inspect

                                                                                        [exEnd]

                                                                                        [exBegin]

        (Image fromFile:'bitmaps/winBitmaps/okSmily_up.bmp' inPackage:'stx:goodies') inspect

                                                                                        [exEnd]

    drawing

                                                                                        [exBegin]

        |imageClass image|

        imageClass := Image implementorForDepth:24.

        image      := imageClass width: 100 height: 50.

        image bits:(ByteArray new:(image bytesPerRow*50)).

        image fillRectangle:(0@0 extent:100@50) withColor:Color yellow.

        image drawRectangle:(10@10 extent:20@20) withColor:Color red.

        image fillRectangle:(40@20 extent:20@20) withColor:Color green.

                                                                                        [exEnd]

    The following examples demonstrate various depth and colorMap variations ...

    inline image:

      default: depth=1 & #blackIs0

                                                                        [exBegin]

        (Image

            width:8 height:8

            fromArray:#( 2r11111111

                         2r10000001

                         2r10000001

                         2r10000001

                         2r10000001

                         2r10000001

                         2r10000001

                         2r11111111 )

        ) edit

                                                                        [exEnd]

      with #whiteIs0 photometric

                                                                        [exBegin]

        ((Image width:8 height:8

               fromArray:#( 2r11111111

                            2r10000001

                            2r10000001

                            2r10000001

                            2r10000001

                            2r10000001

                            2r10000001

                            2r11111111 ))

            photometric:#whiteIs0

        ) edit

                                                                        [exEnd]

      with a colorMap

                                                                        [exBegin]

        ((Image width:8 height:8

               fromArray:#( 2r11111111

                            2r10000001

                            2r10000001

                            2r10000001

                            2r10000001

                            2r10000001

                            2r10000001

                            2r11111111 ))

            colorMap:(Array with:(Color red)

                            with:(Color yellow))

        ) edit

                                                                        [exEnd]

      a depth4 greyScale image:

      (default photometric is #blackIs0)

                                                                        [exBegin]

        (Depth4Image

             width:8

             height:4

             fromArray:#[

                            16r00 16r11 16r22 16r33

                            16r44 16r55 16r66 16r77

                            16r88 16r99 16raa 16rbb

                            16rcc 16rdd 16ree 16rff

                        ]

        ) edit

                                                                        [exEnd]

      the same, magnified:

                                                                        [exBegin]

        ((Depth4Image

             width:4

             height:4

             fromArray:#[

                            16r01 16r23

                            16r45 16r67

                            16r89 16rab

                            16rcd 16ref

                        ])

            magnifiedBy:30

        ) edit

                                                                        [exEnd]

      the following has the same effect:

                                                                        [exBegin]

        ((Image

             width:4

             height:4

             depth:4

             fromArray:#[

                            16r01 16r23

                            16r45 16r67

                            16r89 16rab

                            16rcd 16ref

                        ])

            magnifiedBy:30

        ) edit

                                                                        [exEnd]

      with reverse grey-interpretation:

                                                                        [exBegin]

        ((Depth4Image

             width:4

             height:4

             fromArray:#[

                            16r01 16r23

                            16r45 16r67

                            16r89 16rab

                            16rcd 16ref

                        ])

            photometric:#whiteIs0;

            magnifiedBy:30

        ) edit

                                                                        [exEnd]

      with 1-bit-per-pixel rgb interpretation:

                                                                        [exBegin]

        ((Depth4Image

             width:4

             height:4

             fromArray:#[

                            16r01 16r23

                            16r45 16r67

                            16r89 16rab

                            16rcd 16ref

                        ])

            photometric:#rgb;

            samplesPerPixel:3;

            bitsPerSample:#(1 1 1);

            magnifiedBy:30

        ) edit

                                                                        [exEnd]

      with 1/2/1 rgb interpretation:

                                                                        [exBegin]

        ((Depth4Image

             width:4

             height:4

             fromArray:#[

                            16r01 16r23

                            16r45 16r67

                            16r89 16rab

                            16rcd 16ref

                        ])

            photometric:#rgb;

            samplesPerPixel:3;

            bitsPerSample:#(1 2 1);

            magnifiedBy:30

        ) edit

                                                                        [exEnd]

      a 2/2/0 rgb image (i.e. no blue):

                                                                        [exBegin]

         |i|

         i := Depth4Image

                    width:4

                    height:4

                    fromArray:#[ 16r01 16r23

                                 16r45 16r67

                                 16r89 16rab

                                 16rcd 16ref ].

         i photometric:#rgb.

         i samplesPerPixel:3.

         i bitsPerSample:#(2 2 0).

         i := i magnifiedBy:30.

         i edit.

                                                                        [exEnd]

      a 0/0/4 rgb image (i.e. no red or green):

                                                                        [exBegin]

         |i|

         i := Depth4Image

                    width:4

                    height:4

                    fromArray:#[ 16r01 16r23

                                 16r45 16r67

                                 16r89 16rab

                                 16rcd 16ref ].