"

              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 

                                bitsPerSample samplesPerPixel

                                colorMap photometric 

                                device deviceForm monoDeviceForm

                                fullColorDeviceForm'

         classVariableNames:'lobby

                             DitherAlgorithm NumberOfDitherColors

                             FileFormats'

         poolDictionaries:''

         category:'Graphics-Display Objects'

!

Image comment:'

              All Rights Reserved

written Summer 91 by claus

'!

!Image class methodsFor:'documentation'!

documentation

"

this class provides (some time in the future) representation

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

and will finally replace Form - its still under construction.

An Image keeps all info in a device independent way, but may get

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 even on low color resolution displays possible, to

process and manipulate images without loosing color information.

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

sending an image the 'on:aDevice' message, which will create

a (possibly) dithered form representing the image using the currently

available colors.

Sometimes, a monochrome representation is needed (X servers take monochrome

icons only), this will be created by 'image>>monochromeOn:aDevice'.

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

which needs its own colormap to be installed and allows use of all

256 colors on an 8bit display (not currently implemented).

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

which have the file-format knowledge (see TIFFReader, GIFReader etc.).

The algorithms in here (especially dithering & color allocation) are

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

Much more work is needed and will be done in the near future ...

Dithering is done as:

   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

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

Image initialize.

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>         an Array of 3 arrays containing red,

                                    green and blue values (0..255 biased)

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.

class variables:

lobby               <Registry>      keeps track of known images

DitherAlgorithm     <Symbol>        defines how to dither

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

FileFormats         <Dictionary>    associates filename extensions to

                                    image reader classes

"

! !

!Image class methodsFor:'misc'!

dither:aSymbol

    "define how to dither - #pattern, #error or none;

     error diffusion dithering is currently not implemented,

     pattern dither is currently very slow."

    DitherAlgorithm := aSymbol

    "Image dither:#pattern"

    "Image dither:#error"

    "Image dither:nil"

!

numberOfDitherColors:n

    "define how many colors (i.e. patterns) to use when

     doing a pattern dither (good values are:)"

    NumberOfDitherColors := n

! !

!Image class methodsFor:'initialization'!

initialize

    "initialize class constants"

    "setup tracker of known pictures"

    lobby isNil ifTrue:[

        lobby := Registry new.

        ObjectMemory addDependent:self.

    ].

    "define algorithm to use for dithering - currently only nil or #pattern supported"

    DitherAlgorithm := #pattern.   "will be changed to error as soon as implemented"

    (Display notNil and:[Display hasGreyscales]) ifFalse:[

        NumberOfDitherColors := 64

    ] ifTrue:[

        "as far as I remember, this is about the number of grey values, the eye can distinguish"

        NumberOfDitherColors := 100

    ].

    "define reader classes"

    FileFormats := Dictionary new.

    FileFormats at:'.xbm'  put:XBMReader.

    FileFormats at:'.tiff' put:TIFFReader.

    FileFormats at:'.tif'  put:TIFFReader.

    FileFormats at:'.gif'  put:GIFReader.

    FileFormats at:'.img'  put:IMGReader.

    FileFormats at:'.pcx'  put:PCXReader.

    FileFormats at:'.mac'  put:MacPaintReader.

    FileFormats at:'.im8'  put:SunRasterReader.

    FileFormats at:'.icon' put:SunRasterReader.

    FileFormats at:'.face' put:FaceReader.

    FileFormats at:'.g3'   put:G3FileReader.

    FileFormats at:'.bmp'  put:WindowsIconReader.

    FileFormats at:'.ico'  put:WindowsIconReader.

    FileFormats at:'.jpg'  put:JPEGReader.

    FileFormats at:'.jpeg' put:JPEGReader.

    FileFormats at:'.ppm'  put:PBMReader.

    FileFormats at:'.pbm'  put:PBMReader.

    FileFormats at:'.pgm'  put:PBMReader.

!

flushDeviceImages

    "simply unassign all pictures from their device"

    lobby contentsDo:[:anImage |

        anImage restored

    ]

!

update:something

    "flush all device specific stuff when restarted from a snapshot"

    (something == #restarted) ifTrue:[

        self flushDeviceImages

    ]

! !

!Image class methodsFor:'screen capture'!

fromScreen

    "return an image of the full screen"

    ^ self fromScreen:(0@0 corner:(Display width@Display height))

!

fromScreen:aRectangle

    "return an image of a part of the screen"

    |depth img|

    depth := Display depth.

    img := (self implementorForDepth: depth) new.

    ^ img fromScreen:aRectangle

    "Image fromScreen:(0@0 corner:100@100)"

! !

!Image class methodsFor:'reading from file'!

fromFile:aFileName

    |readerClass image|

    FileFormats associationsDo:[:assoc |

        (aFileName endsWith:(assoc key)) ifTrue:[

            readerClass := assoc value.

            readerClass notNil ifTrue:[

                image := readerClass fromFile:aFileName.

                image notNil ifTrue:[^ image].

            ]

        ]

    ].

    "no known extension - ask all readers if they know

     this format ..."

    FileFormats associationsDo:[:assoc |

        readerClass := assoc value.

        readerClass notNil ifTrue:[

            (readerClass isValidImageFile:aFileName) ifTrue:[

                ^ readerClass fromFile:aFileName

            ]

        ]

    ].

    "nope - unknown format"

'unknown image file format' printNewline.

    ^ nil

    "Image fromFile:'bitmaps/dano.tiff'"

    "Image fromFile:'bitmaps/test.fax'"

    "Image fromFile:'bitmaps/voice.tiff'"

    "Image fromFile:'voice.tiff'"

    "Image fromFile:'../fileIn/bitmaps/claus.gif'"

    "Image fromFile:'../fileIn/bitmaps/garfield.gif'"

    "Image fromFile:'../fileIn/bitmaps/founders.im8'"

    "Image fromFile:'../goodies/faces/next.com/steve.face'"

    "Image fromFile:'/LocalLibrary/Images/OS2/dos3.ico'"

    "Image fromFile:'bitmaps/globe1.xbm'"

    "Image fromFile:'bitmaps/hello_world.icon'"

! !

!Image class methodsFor:'queries'!

implementorForDepth: depth

    "return the class, which best implements images of depth"

    depth == 1 ifTrue:[^ Depth1Image].

    depth == 2 ifTrue:[^ Depth2Image].

    depth == 4 ifTrue:[^ Depth4Image].

    depth == 8 ifTrue:[^ Depth8Image].

    depth == 24 ifTrue:[^ Depth24Image].

    ^ self

! !

!Image methodsFor:'instance release'!

restored

    device := nil.

    deviceForm := nil.

    monoDeviceForm := nil.

    fullColorDeviceForm := nil

!

disposed

    "some Image has been collected - nothing to do"

! !

!Image methodsFor:'inpecting'!

inspect

    "redefined to launch an ImageInspector on the receiver

     (instead of the default InspectorView)."

    ImageInspectorView isNil ifTrue:[

        super inspect

    ] ifFalse:[

        ImageInspectorView openOn:self

    ]

! !

!Image methodsFor:'accessing'!

device

    "return the device, the receiver is associated with.

     Return nil, if the image is unassigned."

    ^ device

!

id

    "return the id of the image on the device.

     Return nil, if the image is unassigned."

    deviceForm isNil ifTrue:[^ nil].

    ^ deviceForm id

!

monochromeId

    "return the id of the monochrome image on the device.

     Return nil, if the image is unassigned."

    monoDeviceForm isNil ifTrue:[^ nil].

    ^ monoDeviceForm id

!

fullColorId

    "return the id of the full color image on the device.

     Return nil, if the image is unassigned."

    fullColorDeviceForm isNil ifTrue:[^ nil].

    ^ fullColorDeviceForm id

!

width

    "return the width of the image"

    ^ width

!

width:aNumber

    "set the width of the image"

    width := aNumber

!

height

    "return the height of the image"

    ^ height

!

height:aNumber

    "set the height of the image"

    height := aNumber

!

samplesPerPixel

    "return the number of samples per pixel in the image.

     The return value is an array of bits-per-plane."

    ^ samplesPerPixel

!

samplesPerPixel:aNumber

    "set the array of samples per pixel"

    samplesPerPixel := aNumber

!

depth

    "return the depth of the image"

    ^ self bitsPerPixel

!

bitsPerSample

    "return the number of bits per sample.

     The return value is an array of bits-per-plane."

    ^ bitsPerSample

!

bitsPerSample:aNumber

    bitsPerSample := aNumber

!

bitsPerPixel

    "return the number of bits per pixel"

    ^ (bitsPerSample inject:0 into:[:sum :i | sum + i])

!

bitsPerRow

    "return the number of bits in one scanline of the image"

    ^  width * (self bitsPerPixel).

!

bytesPerRow

    "return the number of bytes in one scanline of the image"

    |bitsPerRow bytesPerRow|

    bitsPerRow := width * (self bitsPerPixel).

    bytesPerRow := bitsPerRow // 8.

    ((bitsPerRow \\ 8) ~~ 0) ifTrue:[

        bytesPerRow := bytesPerRow + 1

    ].

    ^ bytesPerRow

!

data

    "for backward compatibility - will vanish"

    ^ bytes

!

data:aByteArray

    "for backward compatibility - will vanish"

    bytes := aByteArray

!

bits:aByteArray

    "set the raw data"

    bytes := aByteArray

!

bits

    "return the raw image data; depending on the photometric,

     this has to be interpreted as monochrome, greyscale,

     palette or rgb data. It is also packed to be dense, so

     a 4 bitPerSample palette image will store 2 pixels per byte."

    ^ bytes

!

photometric

    "return the photometric, a symbol such as #palette, #rgb etc."

    ^ photometric

!

photometric:aSymbol

    "set the photometric"

    photometric := aSymbol

!

colorMap:anArrayOfArrays

    colorMap := anArrayOfArrays

!

colorMap

    "return the colormap"

    ^ colorMap

!

at:aPoint

    "retrieve the pixel at aPoint; return a color.

     Pixels start at 0@0 for upper left pixel, end at

     width-1@height-1 for lower right pixel.

     You should not use this method for image-processing, its

     very slow ..."

    ^ self atX:aPoint x y:aPoint y

!

valueAt:aPoint

    "retrieve the pixel at aPoint; return a pixel value.

     Pixels start at 0@0 for upper left pixel, end at

     width-1@height-1 for lower right pixel.

     You should not use this method for image-processing, its

     very slow ..."

    ^ self valueAtX:aPoint x y:aPoint y

!

atX:x y:y

    "retrieve a pixel at x/y; return a color.

     Pixels start at x=0 , y=0 for upper left pixel, end at

     x = width-1, y=height-1 for lower right pixel.

     You should not use this method for image-processing, its

     very slow ..."

    ^ self subclassResponsibility

!

valueAtX:x y:y

    "retrieve the pixel at aPoint; return a pixel value.

     Pixels start at x=0 , y=0 for upper left pixel, end at

     width-1@height-1 for lower right pixel.

     You should not use this method for image-processing, its

     very slow ..."

    ^ self subclassResponsibility

!

at:aPoint put:aColor

    "set the pixel at aPoint to aColor.

     Pixels start at 0@0 for upper left pixel, end at

     width-1@height-1 for lower right pixel.

     You should not use this method for image-processing, its

     very slow ..."

    ^ self atX:aPoint x y:aPoint y put:aColor

!

atX:x y:y put:aColor

    "set the pixel at x/y to aColor.