"

 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.

"

Object subclass:#Image

	instanceVariableNames:'bytes width height bitsPerPixel depth colorMap maxPixelValue

		rowByteSize bitsPerSample samplesPerPixel photometric device

		deviceForm monoDeviceForm fullColorDeviceForm mask'

	classVariableNames:'Lobby DitherAlgorithm NumberOfDitherColors

		CollectGarbageWhenRunningOutOfColors FileFormats

		ImageNotFoundQuerySignal'

	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 (some time in the future) representation

    for all kinds of images (monochrome, greyscale and color)

    and will finally replace Form. 

    For now (only ;-) depths of 1, 2, 4, 8, 16 and 24 are supported.

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

    but may be associated to a device. 

    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 - even on low color resolution displays.

    Usually, you get a device specific representation of the image by

    sending the 

        'on:aDevice' 

    message to it, which will create 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 

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

    it the message 

        'monochromeOn:aDevice'.

    Also, it is planned to generate another hi-color resolution version,

    which uses its own colormap and allows the use of all 256 colors on an 8bit display 

    (this is not currently implemented).

    An images 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

    such as ('.jpg' -> JPEGReader) to the class variable 'FileFormats' 

    (see the classes #initialize method, which dsets up some default, and the

    patches/display.rc files, which add more).

    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 slower fallback methods ...

    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 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.

    [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 #pseudocolor;

                                            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 aproximation 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.

	bitsPerPixel			    not used in ST/X

        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.

        ImageNotFoundNotificationSignal

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

                                            from a file. The parameter is the images

                                            fileName. May return a replacement

                                            image or proceed with nil.

                                            If unhandled, a nil is returned from the

                                            image creation.

    todo:

        there is currently no mask stored/available in the image itself; currently masks

        have to be stored as separate bitmaps. 

        (which is bad for image-file formats, which provide a mask)

        Thus, currently, all images are completely opaque.

    [See also:]

        Form Icon ImageReader

    [author:]

        Claus Gittinger

"

!

examples

"

    reading from a file (many formats are supported):

                                                                        [exBegin]

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

                                                                        [exEnd]

                                                                        [exBegin]

        (Image fromFile:'bitmaps/SmalltalkX.xbm') inspect

                                                                        [exEnd]

                                                                        [exBegin]

        (Image fromFile:'bitmaps/okSmily_up.bmp') inspect

                                                                        [exEnd]

    inline image:

      default: depth=1 & #blackIs0

                                                                        [exBegin]

        (Image width:8 height:8

               fromArray:#( 2r11111111

                            2r10000001

                            2r10000001

                            2r10000001

                            2r10000001

                            2r10000001

                            2r10000001

                            2r11111111 )) inspect

                                                                        [exEnd]

      with #whiteIs0 photometric

                                                                        [exBegin]

        ((Image width:8 height:8

               fromArray:#( 2r11111111

                            2r10000001

                            2r10000001

                            2r10000001

                            2r10000001

                            2r10000001

                            2r10000001

                            2r11111111 ))

            photometric:#whiteIs0)

                 inspect

                                                                        [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)))

                 inspect

                                                                        [exEnd]

      a depth4 greyScale image:

                                                                        [exBegin]

        ((Depth4Image

             width:4 

             height:4

             fromArray:#[ 

                            16r01 16r23

                            16r45 16r67

                            16r89 16rab

                            16rcd 16ref 

                        ])

            magnifiedBy:30)

                 inspect

                                                                        [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)

                 inspect

                                                                        [exEnd]

      with reverse grey-interpretation:

                                                                        [exBegin]

        ((Depth4Image

             width:4 

             height:4

             fromArray:#[ 

                            16r01 16r23

                            16r45 16r67

                            16r89 16rab

                            16rcd 16ref 

                        ])

            photometric:#whiteIs0;

            magnifiedBy:30)

                 inspect

                                                                        [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)

                 inspect

                                                                        [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)

                 inspect

                                                                        [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 inspect.

                                                                        [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 ].

         i photometric:#rgb.

         i samplesPerPixel:3.

         i bitsPerSample:#(0 0 4).

         i := i magnifiedBy:30.

         i inspect.

                                                                        [exEnd]

      a 2plane greyscale image:

                                                                        [exBegin]

        ((Depth2Image

             width:4 

             height:4

             fromArray:#[ 

                            4r0123

                            4r1230

                            4r2301

                            4r3012 

                        ])

            magnifiedBy:30)

                 inspect

                                                                        [exEnd]

      with colors:

                                                                        [exBegin]

        ((Depth2Image

             width:4 

             height:4

             fromArray:#[ 

                            4r0123

                            4r1230

                            4r2301

                            4r3012 

                        ])

            colorMap:(Array with:(Color black)

                            with:(Color red)

                            with:(Color green)

                            with:(Color blue));

            magnifiedBy:30)

                 inspect

                                                                        [exEnd]

      depth8 image with 3/3/2 rgb interpretation:

                                                                        [exBegin]

        ((Depth8Image

             width:16 

             height:16

             fromArray:(ByteArray withAll:(0 to:16rFF)))

            photometric:#rgb;

            samplesPerPixel:3;

            bitsPerSample:#(3 3 2);

            magnifiedBy:30)

                 inspect

                                                                        [exEnd]

      depth8 image with 2/2/2 rgb interpretation:

                                                                        [exBegin]

        ((Depth8Image

             width:8 

             height:8

             fromArray:(ByteArray withAll:(0 to:16r3F)))

            photometric:#rgb;

            samplesPerPixel:3;

            bitsPerSample:#(2 2 2);

            magnifiedBy:30)

                 inspect

                                                                        [exEnd]

    storing (only a few formats are currently supported):

                                                                        [exBegin]

        |img|

        img := Image fromFile:'bitmaps/okSmily_up.bmp'.

        img saveOn:'myImage.tiff'.

        (Image fromFile:'myImage.tiff') inspect

                                                                        [exEnd]

    magnifying (any factor):

                                                                        [exBegin]

        ((Image fromFile:'bitmaps/claus.gif') 

            magnifiedTo:(48@48))

                inspect

                                                                        [exEnd]

                                                                        [exBegin]

        ((Image fromFile:'bitmaps/claus.gif') 

            magnifiedBy:0.7)

                inspect

                                                                        [exEnd]

    rotating (currently, only multiples of 90 degrees are supported):

                                                                        [exBegin]

        ((Image fromFile:'bitmaps/claus.gif') 

            rotated:90)

                inspect

                                                                        [exEnd]

                                                                        [exBegin]

        (((Image fromFile:'bitmaps/claus.gif') 

            magnifiedBy:0.3@0.7) rotated:270)

                inspect

                                                                        [exEnd]

"

! !

!Image class methodsFor:'initialization'!

fileFormats

    "return the collection of supported file formats.

     The returned dictionary maps file-extensions to image reader classes."

    FileFormats isNil ifTrue:[

	self initializeFileFormatTable

    ].

    ^ FileFormats

    "

     Image fileFormats

    "

!

flushDeviceImages

    "simply release all deviceForms"

    Lobby do:[:anImage |

        anImage restored

    ]

    "Modified: 15.6.1996 / 15:45:02 / cg"

!

initialize

    "initialize class constants"

    "setup tracker of known pictures"

    Lobby isNil ifTrue:[

        Lobby := Registry new.

        ObjectMemory addDependent:self.

        "/ define the algorithm to use for dithering - 

        "/ supported values are:

        "/      #threshold

        "/      #ordered