"

 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 bitsPerSample samplesPerPixel colorMap

		photometric device deviceForm monoDeviceForm fullColorDeviceForm'

	classVariableNames:'Lobby DitherAlgorithm NumberOfDitherColors

		CollectGarbageWhenRunningOutOfColors FileFormats'

	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.

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

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

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

    be done in the near future if there is a demand for it ...

    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

    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.

    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.

    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.

"

! !

!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 unassign all pictures from their device"

    Lobby do:[:anImage |

	anImage restored

    ]

!

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 isNil ifTrue:[

	    self initializeFileFormatTable

	].

	CollectGarbageWhenRunningOutOfColors := false

    ]

!

initializeFileFormatTable

    "initialize a default table to map from file extension to reader class.

     The mapping here is a default needed for proper operation of ST/X;

     see the 'smalltalk.rc' startup file for a real (full) map."

    FileFormats := Dictionary new.

    FileFormats at:'.xbm'  put:XBMReader.

    FileFormats at:'.tiff' put:TIFFReader.

    FileFormats at:'.gif'  put:GIFReader.

"/    FileFormats at:'.img'  put:IMGReader.

"/    FileFormats at:'.icon' put:SunRasterReader.

    "

     Image initializeFileFormatTable

    "

!

update:something

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

    (something == #restarted) ifTrue:[

	self flushDeviceImages

    ]

! !

!Image class methodsFor:'instance creation'!

extent:ext depth:d bits:bits

    "ST-80 compatibility; assume 32-bit padding"

    ^ self extent:ext depth:d bits:bits pad:32

!

extent:ext depth:d bits:bits pad:padding

    "ST-80 compatibility"

    ^ self width:ext x height:ext y depth:d fromArray:bits pad:padding

!

extent:ext depth:d palette:aColormap bits:bits pad:padding

    "ST-80 compatibility"

    ^ self width:ext x height:ext y depth:d fromArray:bits pad:padding

!

extent:ext fromArray:bits offset:offset

    "ST-80 compatibility"

    ^ self width:ext x height:ext y fromArray:bits

!

fromFile:aFileName

    "read an image from a file - this methods tries to find

     out the file format itself (by the extension and by contents)

     and lets the appropriate reader read the file."

    |image name nm inStream suffixLen|

    "

     before trying each reader, check if file is readable

    "

    name := aFileName.

    inStream := Smalltalk systemFileStreamFor:name.

    inStream isNil ifTrue:[

    ].

    inStream close.

    "

     get the imageReader class from the files extension

    "

    nm := name.

    (name endsWith:'.Z') ifTrue:[

    ] ifFalse:[

    ].

    suffixLen ~~ 0 ifTrue:[

    ].

    "

     ask the corresponding readerclass first

    "

    FileFormats keysAndValuesDo:[:suffix :readerClass |

    ].

    "

     no known extension - ask all readers if they know

     this format ...

    "

    FileFormats do:[:readerClass |

    ].

    "

     nope - unknown format

    "

    ^ 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/globe1.xbm.Z'

     Image fromFile:'bitmaps/hello_world.icon'

    "

!

fromForm:aForm

    "create & return an Image given a form"

    |cls|

    cls := self.

    cls == Image ifTrue:[

	cls := self implementorForDepth:aForm depth

    ].

    ^ (cls new) fromForm:aForm.

    "

     |f|

     f := Form width:16 height:16.

     f clear.

     f displayLineFromX:0 y:0 toX:15 y:15.

     f inspect.

     (Image fromForm:f) inspect

    "

!

fromImage:anImage

    "create & return an Image given another image. This can be used to

     convert an image to another depth."

    (self == Image or:[anImage class == self]) ifTrue:[^ anImage].

    ^ self new fromImage:anImage.

    "

     |i1 i8|

     i1 := Image fromFile:'bitmaps/SBrowser.xbm'.

     i8 := Depth8Image fromImage:i1.

     i8 inspect

    "

!

fromSubImage:anImage in:aRectangle

    "create & return an Image from a rectangular area in another image. 

     This can also be used to get a subimage in another depth."

    ^ self new fromSubImage:anImage in:aRectangle.

    "

     |i1 i8|

     i1 := Image fromFile:'bitmaps/garfield.gif'.

     i8 := Depth8Image fromSubImage:i1 in:(0@0 corner:20@20).

     i8 inspect

    "

    "Created: 20.9.1995 / 01:05:43 / claus"

!

new

    "create a new image. Redefined to set the photometric to

     greyScale with black being 0 as default."

    ^ super new photometric:#blackIs0

!

width:w height:h

    "create a new image, given width, height. Assume a depth of 1."

    |cls|

    cls := self.

    cls == Image ifTrue:[

	cls := self implementorForDepth:1

    ].

    ^ cls new width:w height:h depth:1 

!

width:w height:h depth:d

    "create a new image, given width, height and depth"

    ^ (self implementorForDepth:d) new

	width:w height:h depth:d

!

width:w height:h depth:d fromArray:pixelData

    "create a new image, given width, height, depth and data.

     Data must be a ByteArray containing correctly aligned bits for the specified

     depth (8-bit padded)."

    ^ (self implementorForDepth:d) new width:w height:h depth:d fromArray:pixelData

    "

     Image width:8 

	   height:8

	   depth:1

	   fromArray:#[2r11001100

		       2r00110011

		       2r11001100

		       2r00110011

		       2r11001100

		       2r00110011

		       2r11001100

		       2r00110011].

    "

    "

     Image width:8 

	   height:8

	   depth:2 

	   fromArray:#[4r1100 4r1100

		       4r0011 4r0011

		       4r1100 4r1100

		       4r0011 4r0011

		       4r1100 4r1100

		       4r0011 4r0011

		       4r1100 4r1100

		       4r0011 4r0011].

    "

    "

     Image width:8 

	   height:8

	   depth:4 

	   fromArray:#[4r0001 4r0001

		       4r0011 4r0011

		       4r1100 4r1100

		       4r0011 4r0011

		       4r1100 4r1100

		       4r0011 4r0011

		       4r1100 4r1100

		       4r0011 4r0011].

    "

!

width:w height:h depth:d fromArray:pixelData pad:padding

    "create a new image, given width, height, depth and data.

     Data must be a ByteArray containing correctly aligned bits for the specified

     depth."

    |img newBits srcRowBytes dstRowBytes srcIndex dstIndex|

    img := (self implementorForDepth:d) new width:w height:h depth:d .

    padding ~~ 8 ifTrue:[

	"must repad; ST/X uses byte padding, while ST-80 uses longword

	 padding. This is stupid, and may be changed in ST/X with future versions.

	"

	dstRowBytes := img bytesPerRow.

	srcRowBytes := ((w * d + padding - 1) bitShift:-5) bitShift:2.