Smalltalk/X Webserver

Documentation of class 'Image':

Class: Image

Inheritance
Description
Related information
Class protocol
Instance protocol
Examples

Inheritance:

   Object
   |
   +--Image
      |
      +--CachedImage
      |
      +--Depth16Image
      |
      +--Depth1Image
      |
      +--Depth24Image
      |
      +--Depth2Image
      |
      +--Depth32Image
      |
      +--Depth48Image
      |
      +--Depth4Image
      |
      +--Depth64Image
      |
      +--Depth8Image

Package:: stx:libview

Category:: Graphics-Images

Version:: rev: 1.624 date: 2019/08/04 20:18:05; user: cg; file: Image.st directory: libview; module: stx stc-classLibrary: libview

Author:: Claus Gittinger

Description:

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 losing
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 were 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 (8x8x8) or 16bit (5x5x6) truecolor, 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 section 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 attributes,
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
approximation of the image on device.

fullColorDeviceForm <Form> the device form which gives the best
possible approximation 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

Related information:

    Form
    Icon
    ImageReader

Class protocol:

Signal constants

badImageFormatQuerySignal: return the (query-) signal, which is raised if some
bitmap-image could not be loaded due to an unrecognized format.
If unhandled, the image-load returns nil.
Otherwise, it returns whatever the handler proceeds with.
The exception gets either the images fileName or an input stream
as parameter
cannotRepresentImageSignal: return the signal, which is raised if some
bitmap-image could not be saved in the requested format.
This happens for example, if a true color image is saved in
xpm format or a color image saved in xbm format.
Applications should either ask the class before saving
(via #canRepresent:) or handle the error and use an alternative
format then.
fileCreationErrorSignal: return the signal which is raised if a file could not be
created in an image-save operation.
imageErrorSignal: return the parent of all image signals
imageLoadErrorSignal: return the parent of all image load error signals
imageNotFoundQuerySignal: return the (query-) signal, which is raised if some
bitmap-image could not be loaded from a file.
If unhandled, the image-load returns nil.
Otherwise, it returns whatever the handler proceeds with.
The exception gets the images fileName as parameter
imageSaveErrorSignal: return the parent signal of all image-save errors.
informationLostQuerySignal: return the (query-) signal, which is raised if some
bitmap-image is saved in a format which cannot represent
the full image (for example: the images mask).
If unhandled, the image-save proceeds.
Otherwise, the handler may show a warn box or whatever and decide
to proceed or abort the saving.
noMaskButAlphaSupportedQuerySignal: return the (query-) signal, which is raised if some
bitmap-image with a mask is saved in a format which cannot represent
the mask but instead supports an alpha channel.
If unhandled, the image-save proceeds (with mask converted to alpha channel).
Otherwise, the handler may show a warn box or whatever and decide
to proceed or abort the saving.
noMaskSupportedQuerySignal: return the (query-) signal, which is raised if some
bitmap-image with a mask is saved in a format which cannot represent
the mask.
If unhandled, the image-save proceeds (without mask).
Otherwise, the handler may show a warn box or whatever and decide
to proceed or abort the saving.
unrepresentableColorSignal: return the signal, which is raised if some color is not
representable in the image (when storing a pixel).

cleanup

releaseResourcesOnDevice: aDevice

this is sent when a display connection is closed,
to release all cached Images from that device

usage example(s):

      self releaseResourcesOnDevice:Screen current

file reading

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.
Also, unless the path is absolute,
all bitmap directories along the searchPath are checked
for the file; thus, you can place your private images into a
separate directory, thereby overriding system bitmaps easily.
If the file is unreadable or does not contain an appropriate image,
the ImageNotFoundQuerySignal is raised, which may be handled to
proceed with some replacement image. If unhandled, nil is returned.

usage example(s):

     Image fromFile:'bitmaps/gifImages/claus.gif' inPackage:'stx:goodies'
     Image fromFile:'bitmaps/gifImages/garfield.gif' inPackage:'stx:goodies'

     Image fromFile:'bitmaps/winBitmaps/a11.ico' inPackage:'stx:goodies'
     Image fromFile:'bitmaps/xpmBitmaps/countries/czech.xpm' inPackage:'stx:goodies'
     Image fromFile:'bitmaps/xpmBitmaps/countries/czech.xpm.gz' inPackage:'stx:goodies'
     Image fromFile:'Demos/bitmaps/hello_world.icon' inPackage:'stx:clients'

usage example(s):

     Image fromFile:'fooBar'

usage example(s):

giving a message for non-existing images:

     Image imageNotFoundQuerySignal
     handle:[:ex |
        Transcript showCR:ex description.
        ex proceedWith:nil
     ] do:[
         Image fromFile:'fooBar'
     ]

usage example(s):

giving a replacement for non-existing images:

     Image imageNotFoundQuerySignal
     answer:(Image fromFile:'libtool/bitmaps/SmalltalkX.xbm')
     do:[
         Image fromFile:'fooBar'
     ]

fromFile: aFileName inPackage: aPackage

read an image for a package from a file.
The filename is assumed to be package-relative (i.e. bitmaps/filename).
This methods tries to find out the file format itself (by the extension and by contents)
and lets the appropriate reader read the file.
Also, all bitmap directories along the searchPath are checked
for the file; thus, you can place your private images into a
separate directory, thereby overriding system bitmaps easily.
If the file is unreadable or does not contain an appropriate image,
the ImageNotFoundQuerySignal is raised, which may be handled to
proceed with some replacement image. If unhandled, nil is returned.

usage example(s):

     Image fromFile:'libtool/bitmaps/SBrowser.xbm'
     Image fromFile:'bitmaps/SBrowser.xbm' inPackage:'stx:libtool'
     Image fromFile:'garfield.gif' inPackage:'stx:goodies/bitmaps/gifImages'

fromFile: aFileName on: aDevice

read an image from a file and prepare a device representation.
Return nil (or whatever a handler returned),
if the file is unreadable or does not contain an appropriate image.

fromFile: aFileName resolution: res

read an image from a file and (if required) scale the image
as appropriate (only req'd for very high resolution displays).
Return nil (or whatever a handler returned),
if the file is unreadable or does not contain an appropriate image.

fromFile: aFileName resolution: dpi on: aDevice

read an image from a file and (if required) scale the image
as appropriate (only req'd with very high resolution displays).
Prepare a device representation.
Return nil (or whatever a handler returned),
if the file is unreadable or does not contain an appropriate image.

fromStream: aStream

read an image from a stream - this methods tries to find
out the file format itself (by contents)
and lets the appropriate reader read the file.
To do this, the stream must be positionable.
Return nil (or whatever a handler returned),
if the stream does not contain an appropriate image.

fromStream: aStream using: aReaderClass

read an image from a stream, given an imageReaderClass.
Use this, if you know the file's format, but it has an invalid
extension (or non-definite header), so #fromStream: could not
find out the images format.
Return nil (or whatever a handler returned),
if the stream does not contain an appropriate image.

initialization

addReader: aReaderClass suffix: aSuffix

register an additional image reader.
This is provided for subclasses, to regster themself when
loaded (or from the startup scripts)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

addReader: aReaderClass suffix: aSuffix mimeType: mimeType

register an additional image reader.
This interface is kept for backward compatibility.
The knowledge has been concentrated in MIMETypes

** This is an obsolete interface - do not use it (it may vanish in future versions) **

fileFormats

return the collection of supported file formats.
The returned dictionary maps file-extensions to image reader classes.

usage example(s):

     Image fileFormats

flushDeviceImages

simply release all deviceForms

initialize

initialize class constants

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'/'display.rc' startup files for a real (full) map.

usage example(s):

     Image initializeFileFormatTable

initializeMIMETable

initialize a default table to map from mime type to reader class.
The mapping here is a default needed for proper operation of ST/X;
see the 'smalltalk.rc'/'display.rc' startup files for a real (full) map.

usage example(s):

     Image initializeMIMETable

update: something with: aParameter from: changedObject

flush all device specific stuff when restarted from a snapshot

instance creation

extent: ext

create a new image, given extent.
Assume a depth of 1, unless an explicit imageClass is the receiver.

extent: ext depth: d

ST-80 compatibility

extent: ext depth: d antiAliasedPalette: aBasicColorArray bgColor: bgColor

|colorMap aaImgArray|

colorMap := Array with:Color white with:Color blue.

aaImgArray := Depth8Image extent:300@400 depth:8 antiAliasedPalette:colorMap bgColor:Color white.
aaImgArray last
fillAntiAliasedArc:200@200
radius:80
from:0
angle:360
withColor:Color blue
antiAliasedPalette:aaImgArray first
startWith:aaImgArray second.

aaImgArray last inspect.

|colorMap aaImgArray|

colorMap := Array with:Color white with:Color black with:Color red with:Color blue.

aaImgArray := Depth8Image extent:300@400 depth:8 antiAliasedPalette:colorMap bgColor:Color white.
aaImgArray last fillAntiAliasedArc:205@195 radius:80 from:0 angle:90 withColor:Color red
colorDictionary:aaImgArray first
blendStart:aaImgArray second.
aaImgArray last fillAntiAliasedArc:200@200 radius:80 from:90 angle:270 withColor:Color blue
colorDictionary:aaImgArray first
blendStart:aaImgArray second.

aaImgArray last inspect.

extent: ext depth: d antiAliasedPalette: aBasicColorArray bgColor: bgColor mixedArray: mixedArray

emptyBits := ByteArray new:(newImage bytesPerRow * ext y).

extent: ext depth: d bits: bits

ST-80 compatibility; assume 32-bit padding

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

ST-80 compatibility

extent: ext depth: d bitsPerPixel: bpp palette: aColormap usingBits: bits

ST-80 compatibility

extent: ext depth: d palette: aColormap

create & return a blank image of the given size.
ST-80 compatibility

usage example(s):

     Image extent:16@16 depth:8 palette:nil
     Image extent:16@16 depth:4 palette:nil
     Image extent:16@16 depth:2 palette:nil

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

ST-80 compatibility

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

ST-80 compatibility

extent: ext fromArray: bits offset: offset

ST-80 compatibility

fromAlphaInImage: anImage

create & return an Image from the alpha channel ofanother image.
If I am a depth1 image, set the pixels for alpha > 127;
if I am a depth8 image, set the pixels to the alpha values.

fromDeviceForm: aForm maskForm: aMaskFormOrNil

create & return an image form aForm that is already on a device

fromForm: aForm

create & return an Image given a aForm

fromImage: anImage

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

fromImage: anImage photometric: photometricOrNil

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

fromSubForm: aRectangle in: aForm

create & return an subImage given a aForm

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.
As with layouts, the rectangle may contain integers (= nr of pixels) or float numbers (= relative size).
Color precision may be lost, if conversion is from a higher depth image.
For palette & rgb images, this may fail if a color cannot be represented.

new

create a new image. Redefined to set the photometric to
greyScale with black being 0 as default.

newForDepth: depth

create a new image. Redefined to set the photometric to
greyScale with black being 0 as default.

usage example(s):

     Image newForDepth:8

width: w height: h

create a new image, given width, height.
Assume a depth of 1, unless an explicit imageClass is the receiver.

width: w height: h depth: d

create a new image, given width, height and depth

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

usage example(s):

     Image width:8
           height:8
           depth:1
           fromArray:#[2r11001100
                       2r00110011
                       2r11001100
                       2r00110011
                       2r11001100
                       2r00110011
                       2r11001100
                       2r00110011].

usage example(s):

     Image width:8
           height:8
           depth:2
           fromArray:#[4r1100 4r1100
                       4r0011 4r0011
                       4r1100 4r1100
                       4r0011 4r0011
                       4r1100 4r1100
                       4r0011 4r0011
                       4r1100 4r1100
                       4r0011 4r0011].

usage example(s):

     Image width:8
           height:8
           depth:4
           fromArray:#[16r00 16r01 16rf0 16rf1
                       16r02 16r03 16rf2 16rf3
                       16r04 16r05 16rf4 16rf5
                       16r06 16r07 16rf6 16rf7
                       16r08 16r09 16rf8 16rf9
                       16r0a 16r0b 16rfa 16rfb
                       16r0c 16r0d 16rfc 16rfd
                       16r0e 16r0f 16rfe 16rff].

usage example(s):

     Image width:8
           height:8
           depth:16
           fromArray:#(1 1 1 1 1 1 1 1
                       2 2 2 2 2 2 2 2
                       3 3 3 3 3 3 3 3
                       4 4 4 4 4 4 4 4
                       5 5 5 5 5 5 5 5
                       6 6 6 6 6 6 6 6
                       7 7 7 7 7 7 7 7
                       8 8 8 8 8 8 8 8
                      ) asWordArray.

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.

width: w height: h fromArray: anArray

create a new image, given width, height. Assume a depth of 1 of the
receiving class is Image.
Data must be a ByteArray containing correctly aligned bits for depth 1
(i.e. 8 bits per byte).

usage example(s):

     Image width:8
           height:8
           fromArray:#[2r11001100
                       2r00110011
                       2r11001100
                       2r00110011
                       2r11001100
                       2r00110011
                       2r11001100
                       2r00110011].

width: w height: h photometric: photometric

create a new image, given width, height.
Assume a depth of 1, unless an explicit imageClass is the receiver.

width: w height: h photometric: photometric bitsPerSample: bitsPerSample

create a new image, given width, height.
Assume a depth of 1, unless an explicit imageClass is the receiver.

misc

bytesPerRowForWidth: width bitsPerPixel: bitsPerPixel: return the number of bytes in one scanline of an image.
(if there is no padding (except byte padding)
ditherAlgorithm: return the way we dither -
#threshold, or nil -> no dither
#pattern, or #ordered -> orderedDither (ugly, but fast)
#error or #floydSteinberg -> errorDiffusion; much better
#burkes -> errorDiffusion; even better.
ditherAlgorithm: aSymbol: define how to dither -
#threshold, or nil -> no dither
#pattern, or #ordered -> orderedDither (ugly, but fast)
#error or #floydSteinberg -> errorDiffusion; much better
#burkes -> errorDiffusion; even better.
numberOfDitherColors: n: define how many colors (i.e. patterns) to use when
doing a pattern dither
orderedDitherMatrixOfSize: sz

queries

bytesPerRowForWidth: width depth: bitsPerPixel padding: padding

helper - return the number of bytes in one scanline of an image,
if scanlines are to be padded to padding-bits and the depth of the image is d.

usage example(s):

     self bytesPerRowForWidth:7 depth:1 padding:8
     self bytesPerRowForWidth:7 depth:1 padding:16
     self bytesPerRowForWidth:7 depth:1 padding:32

     self bytesPerRowForWidth:15 depth:1 padding:8
     self bytesPerRowForWidth:15 depth:1 padding:16
     self bytesPerRowForWidth:15 depth:1 padding:32

defaultImageFileWriter

only used, if a file is saved with no particular extension
or explicit writer given.
For now, default to tiff format.
Will change to png, as soon as all mask formats are fully supported by it

defaultPhotometric

return the default photometric pixel interpretation.
This may be a somewhat old leftover from times, when tiff was the first image file type to be read.
Much better would be to always have some (possibly fake and virtual) colormap around, and ask that one.
However, in the meantime, many other classes depend on that, so that it should be kept as an API
- even when the internal representation will be replaced by something better in the future.

imageDepth

return the depth of images represented by instances of
this class.
Must be redefined in concrete subclasses

** This method raises an error - it must be redefined in concrete classes **

imageFileSuffixes

return a collection of suffixes which are recognized as image-file suffix

usage example(s):

     Image imageFileSuffixes

imageReaderClassForMIME: mimeType

return an appropriate imageReader class for a given mime type;
nil if there is none (or it did not install itself)

usage example(s):

     Image imageReaderClassForMIME:'image/tiff'
     Image imageReaderClassForMIME:'image/x-portable-pixmap'

imageReaderClassForSuffix: aSuffix

return an appropriate imageReader class for a given file-suffix;
nil if there is none (or it did not install itself)

usage example(s):

     Image imageReaderClassForSuffix:'tiff'
     Image imageReaderClassForSuffix:'foo'

implementorForDepth: depth

return the class, which best implements images of depth

isAbstract

isImageFileSuffix: aSuffix

return true, if the given suffix is known to be an image files suffix

usage example(s):

     Image isImageFileSuffix:'gif'
     Image isImageFileSuffix:'xbm'
     Image isImageFileSuffix:'foo'

mimeTypeFromSuffix: suffix

search my suffix information for a mime type and
return it; return nil if unknown

usage example(s):

     Image mimeTypeFromSuffix:'gif'
     Image mimeTypeFromSuffix:'tiff'
     Image mimeTypeFromSuffix:'foobar'

screen capture

fromScreen

return an image of the full screen.
WARNING: this temporarily grabs the display
it may not work from within a buttonMotion
(use #fromScreen:on:grab: with a false grabArg then).

usage example(s):

     Image fromScreen
     Image fromScreen inspect

fromScreen: aRectangle

return an image of a part of the screen.
WARNING: this temporarily grabs the display
it may not work from within a buttonMotion
(use #fromScreen:on:grab: with a false grabArg then).

usage example(s):

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

fromScreen: aRectangle on: aDevice

return an image of a part of a screen, which may be on
another display device.
WARNING: this temporarily grabs the display
it may not work from within a buttonMotion
(use #fromScreen:on:grab: with a false grabArg then).

usage example(s):

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

usage example(s):

get a snapshot of your friends screen ...

     |dpy2|

     dpy2 := XWorkstation new initializeFor:'idefix:0'.
     (Image fromScreen:(dpy2 bounds) on:dpy2) inspect

fromScreen: aRectangle on: aDisplay grab: doGrab

return an image of a part of the screen, which may be on
another Display. If the doGrab argument is true, the display
is grabbed (i.e. blocked for others) and a camera cursor is
shown while the readout is done.
WARNING: with doGrab true, this temporarily grabs the display
and it may not work from within a buttonMotion
(use with a false grabArg then).

usage example(s):

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

fromScreenArea

return an image of a part of the screen;
let user specify screen area.
This is the same as #fromUser - kept for backward compatibility.
Use #fromUser for ST-80 compatibility.
WARNING: this temporarily grabs the display
it may not work from within a buttonMotion
(use #fromScreen:on:grab: with a false grabArg then).

usage example(s):

     Image fromScreenArea
     Image fromScreenArea inspect

fromUser

return an image of a part of the screen; let user specify screen area.
Same as fromScreenArea, for ST-80 compatibility.
WARNING: this temporarily grabs the display
it may not work from within a buttonMotion
(use #fromScreen:on:grab: with a false grabArg then).

usage example(s):

     Image fromUser
     Image fromUser inspect

fromView: aView

return an image taken from a view's contents as currently
on the screen. The returned image has the same depth and photometric
as the Display.
Notice that for invisible or partial covered views,
the returned Image is NOT correct.
You may want to raise the view before using this method.
WARNING: this temporarily grabs the display
it may not work from within a buttonMotion
(use #fromView:grab: with a false grabArg then).

usage example(s):

     Image fromView:(Launcher allInstances first window topView)
     Image fromView:(BrowserView allInstances first topView)

fromView: aView grab: doGrab

return an image taken from a view's contents as currently
on the screen. If the doGrab argument is true, the display
is grabbed (i.e. blocked for others) and a camera cursor is
shown while the readout is done.
The returned image has the same depth and photometric
as the Display.
Notice that for invisible or partial covered views,
the returned Image is NOT correct.
You may want to raise the view before using this method.
WARNING: with doGrab true, this temporarily grabs the display
and it may not work from within a buttonMotion
(use with a false grabArg then).

fromView: aView grab: doGrab withDecoration: withDecoration

return an image taken from a view's contents as currently
on the screen, optionally with decoration included.
If the doGrab argument is true, the display
is grabbed (i.e. blocked for others) and a camera cursor is
shown while the readout is done.
The returned image has the same depth and photometric
as the Display.
Notice that for invisible or partial covered views,
the returned Image is NOT correct.
You may want to raise the view before using this method.
WARNING: with doGrab true, this temporarily grabs the display
and it may not work from within a buttonMotion
(use with a false grabArg then).

usage example(s):

     Transcript topView raise. (Image fromView:Transcript topView grab:false withDecoration:false) inspect
     Transcript topView raise. (Image fromView:Transcript topView grab:false withDecoration:true) inspect

Instance protocol:

Compatibility-Squeak

boundingBox

colormapIfNeededForDepth: d

colorsFromArray: anArrayOfRGBTriples

for squeak compatibility with ColorForm:
set the colorMap from an array of rgb triples, each value being in 0..1.

usage example(s):

     Depth8Image new
        colorsFromArray:#( (0.5 0.5 0.5) (0.25 0.0 0.0) (0.0 0.25 0.5))

fill: aRectangle fillColor: aColor

fill the rectangular area specified by aRectangle with the given color

fillBlack: aRectangle

fill the rectangular area specified by aRectangle with the black color

fillRectangle: aRectangle color: aColor

fill the rectangular area specified by aRectangle with the given color

fillWhite: aRectangle

fill the rectangular area specified by aRectangle with the white color

isTransparentAt: aPoint

Compatibility-VW

asCachedImage: return the receiver associated to the current screens device.
For ST-80 compatibility
(ST/X uses Image for both device- and nonDevice-images)
asRetainedMedium: return the receiver associated to the current screens device.
For ST-80 compatibility
(ST/X uses Image for both device- and nonDevice-images)
bounds: newBounds
containsPoint: aPoint: in st-80, images are visualComponents ...
convertToPalette: aColormap renderedBy: anImageRenderer: this does not really mimicri the corresponding ST-80 functionality
paintBasis: huh - whats that;
I guess, I have to return Color for images without a mask,
and CoverageValue for those with a mask; for now, always return Color
preferredBounds
tile: bounds from: origin in: tile rule: rule
valueAtPoint: aPoint put: aColorValue

accessing

bitsPerSample: return the number of bits per sample.
The return value is an array of bits-per-plane.
colorMap: return the colormap
colorMap: newColorMap: set the colorMap; this also sets the photometric to a useful default.
colorMapFromArray: anArray: set the colorMap by reading colors from an array with rgb-byte values.
The (byte-)Array argument should be of the form:
#( red0 green0 blue0 red1 green1 blue1 ... redN greenN blueN)
where each component must be a byteValue in 0..255.
colorMapFromRGBValueArray: anArray: set the colorMap by reading colors from an array with rgb-integer values.
The (integer-)Array argument should be of the form:
#( rgb0 rgb1 ... rgbN)
where each element must be an rgbValue in 0..FFFFFF.
container: aVisualContainer: ignored here - added to allow images to be used like
VisualComponents (later, Image should inherit from it)
depth: return the depth of the image
device: return the device, the receiver is associated with.
Return nil, if the image is unassigned.
drawableId: return the id of the image on the device.
Return nil, if the image is unassigned.
extent: return the images extent
fileName: return the value of the instance variable 'fileName' (automatically generated)
fileName: something: set the value of the instance variable 'fileName' (automatically generated)
fullColorId: return the id of the full color image on the device.
Return nil, if the image is unassigned.
graphicsDevice: same as #device - for ST-80 compatibility
height: return the height of the image
id
imageSequence: return the frameSequence of which this image is a part of;
nil if it is not part of a sequence.
imageSequence: aCollection: private entry for imageReaders - set the frameSequence of which
this image is a part of
mask
mask: anotherImage: set the images mask - currently, this may be nil or a Depth1Image.
(it is planned to support alpha information in a Depth8 maskImage in
the near future).
For depth1 masks: each pixel of the image where a corresponding
1-bit is present in the mask will be drawn;
0-bit mask pixels lead to transparent pixels.

For depth8 masks: (future):
each pixel specifies the alpha value (0..255),
which specifies the transparency of that pixel.
0 means completely transparent, 255 means completely
opaque. The 1-plane mask is a special case of this,
interpreting a 0 as a 0 alpha value and 1's as an
alpha value of 255.
maskedPixelsAre0: return true if masked pixels have been cleared to zero
maskedPixelsAre0: aBoolean: set/clear the flag which states if masked pixels
have been set to zero. Knowing this to be true allows
faster drawing of the image later; (however, not setting
it will still produce correct output).
This flag is typically set by image readers.
metaData
metaData: something
monochromeId: return the id of the monochrome image on the device.
Return nil, if the image is unassigned.
palette: return the colormap; ST-80 compatibility
palette: aColormap: set the colormap; ST-80 compatibility
photometric: return the photometric, a symbol such as #palette, #rgb etc.
This may be a somewhat old leftover from times, when tiff was the first image file type to be read.
Much better would be to always have some (possibly fake and virtual) colormap around, and ask that one.
However, in the meantime, many other classes depend on that, so that it should be kept as an API
- even when the internal representation will be replaced by something better in the future.
samplesPerPixel: return the number of samples per pixel in the image.
setColorMap: newColorMap: Modified (format): / 03-02-2017 / 16:39:48 / cg
width: return the width of the image

accessing-pixels

at: aPoint: WARNING: for now, this returns a pixel's color
(backward compatibility with ST/X)
In the future, this will return a pixel value (ST-80 compatibility)
Use #colorAt: - for future compatibility.

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 ...
(it is meant to access individual pixels - for example, in a bitmap editor)

** This is an obsolete interface - do not use it (it may vanish in future versions) **
at: aPoint put: aColor: WARNING: for now, this expects a pixel's color
(backward compatibility with ST/X)
In the future, this will expect a pixel value (ST-80 compatibility)
Use #colorAt:put: - for future compatibility.

set the pixel at aPoint to aColor.
Pixels start at 0@0 for the 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 ...
(it is meant to access individual pixels - for example, in a bitmap editor)
atImageAndMask: aPoint put: aColorOrPixelOrNil: set the pixel at x/y to aColor.
If aColor is a mask color (i.e. Color noColor) the mask pixel will be set to 0 (transparent),
otherwise to 1. Nil is treated like noColor.
(used by the bitmap editor)
atImageAndMask: aPoint putValue: aPixelValueOrNil: set the pixel at x/y to aColor.
If aPixelValueOrNil is nil, the mask pixel will be set to 0 (transparent),
otherwise to 1. (used by the bitmap editor)
atPoint: aPoint: ST-80 compatibility: return the pixelValue at:aPoint.
atPoint: aPoint put: aPixelValue: ST-80 compatibility: set the pixelValue at:aPoint.
atX: x y: y: WARNING: for now, this returns a pixel's color
(backward compatibility with ST/X)
In the future, this will return a pixel value (ST-80 compatibility)
Use #colorAt: - for future compatibility.

Retrieve a pixel at x/y; 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 ...
(it is meant to access individual pixels - for example, in a bitmap editor)

** This is an obsolete interface - do not use it (it may vanish in future versions) **
atX: x y: y put: aColor: WARNING: for now, this expects a pixel's color
(backward compatibility with ST/X)
In the future, this will expect a pixel value (ST-80 compatibility)
Use #colorAt:put: - for future compatibility.

set the pixel at x/y to aColor.
Pixels start at 0@0 for the upper left pixel, end at
(width-1)@(height-1) for the lower right pixel.
This method checks if the color can be stored in the image.
(i.e. if the receiver is a palette image, the color must be present in there).
You should not use this method for image-processing, it is very slow ...
(it is meant to access individual pixels - for example, in a bitmap editor)
atX: x y: y putValue: aPixelValue: set the pixel at x/y to aPixelValue.
The interpretation of the pixelValue depends on the photometric
and the colormap. (see also: Image>>atX:y:put:)
Pixels start at 0@0 for the upper left pixel, end at
(width-1) @ (height-1) for the lower right pixel.
You should not use this method for image-processing, its
very slow ...
(it is meant to access individual pixels - for example, in a bitmap editor)

** This is an obsolete interface - do not use it (it may vanish in future versions) **
bits: return the raw image data (pixel 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, whereas a 2-bitPerPixel image will store
4 pixels per byte.
colAt: x into: aPixelBuffer: fill aBuffer with pixel values retrieved from a single column.
(eg. a vertical span)
Notice: row/column coordinates start at 0.
colAt: x into: aPixelBuffer startingAt: startIndex: fill aBuffer with pixel values retrieved from a single column.
(eg. a vertical span)
Notice: row/column coordinates start at 0.
This is a slow fallBack method, which works with any depth;
concrete image subclasses should redefine this for more performance.
colAt: x putAll: pixelArray: store a single column's pixels from bits in the argument;
(eg. a vertical span)
Notice: row/column coordinates start at 0.
This is a slow fallBack method, which works with any depth;
concrete image subclasses should redefine this for more performance.
colAt: x putAll: pixelArray startingAt: startIndex: store a single row's pixels from bits in the pixelArray argument.
(eg. a vertical span)
Notice: row/column coordinates start at 0.
This is a slow fallBack method, which works with any depth;
concrete image subclasses should redefine this for more performance.
colorAt: aPoint: retrieve a pixel at x/y; 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 ...
(it is meant to access individual pixels - for example, in a bitmap editor)
colorAt: aPoint put: aColor
colorAtX: x y: y: retrieve a pixel at x/y; 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 ...
(it is meant to access individual pixels - for example, in a bitmap editor)
colorAtX: x y: y put: aColor: set the pixel at x/y to aColor.
Pixels start at 0@0 for the upper left pixel, end at
(width-1)@(height-1) for the lower right pixel.
This method checks if the color can be stored in the image.
(i.e. if the receiver is a palette image, the color must be present in there).
You should not use this method for image-processing, it is very slow ...
(it is meant to access individual pixels - for example, in a bitmap editor)
data: for backward compatibility - will vanish

** This is an obsolete interface - do not use it (it may vanish in future versions) **
data: aByteArray: for backward compatibility - will vanish

** This is an obsolete interface - do not use it (it may vanish in future versions) **
maskAt: aPoint: retrieve the maskValue at aPoint - an integer number which is
0 for masked pixels (invisible), 1 for unmasked (visible).
For images without mask, 1 is returned for all pixels.
maskAt: aPoint put: maskValue: set the maskValue at aPoint - an integer number which is
0 for masked pixels (invisible), 1 for unmasked (visible).
maskAtX: x y: y: retrieve the maskValue at aPoint - an integer number which is
0 for masked pixels (invisible), 1 for unmasked (visible).
For images without mask, 1 is returned for all pixels.
maskAtX: x y: y put: maskValue: set the maskValue at aPoint - an integer number which is
0 for masked pixels (invisible), 1 for unmasked (visible).
pixelAt: aPoint: retrieve a pixel at x/y; 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 ...
(it is meant to access individual pixels - for example, in a bitmap editor)
pixelAt: aPoint put: aPixelValue: set the pixel at x/y to aPixelValue.
The interpretation of the pixelValue depends on the photometric
and the colormap. (see also: Image>>atX:y:put:)
Pixels start at 0@0 for the upper left pixel, end at
(width-1) @ (height-1) for the lower right pixel.
You should not use this method for image-processing, its
very slow ...
(it is meant to access individual pixels - for example, in a bitmap editor)
pixelAtX: x y: y: retrieve the pixelValue at aPoint; return a pixel (an integer number).
Pixels start at 0/0 for upper left pixel, and end at
width-1@height-1 for lower right pixel.
The returned number's interpretation depends on the photometric
and the colormap. (see also Image>>at: and Image>>atX:y:)
You should not use this method for image-processing of
big images, it's very slow ...
(it is meant to access individual pixels - for example, in a bitmap editor)

** This method raises an error - it must be redefined in concrete classes **
pixelAtX: x y: y put: aPixelValue: set the pixel at x/y to aPixelValue.
The interpretation of the pixelValue depends on the photometric
and the colormap. (see also: Image>>atX:y:put:)
Pixels start at 0@0 for the upper left pixel, end at
(width-1) @ (height-1) for the lower right pixel.
You should not use this method for image-processing, its
very slow ...
(it is meant to access individual pixels - for example, in a bitmap editor)

** This method raises an error - it must be redefined in concrete classes **
rgbValueAt: aPoint: retrieve a pixel's rgb value at x/y;
return a 24bit rgbValue (rrggbb, red is MSB),
or 32bit for alpha images (aarrggbb, alpha is MSB).
Pixels start at 0@0 for the upper left pixel,
and end at (width-1)@(height-1) for the lower right pixel.
rgbValueAtX: x y: y: retrieve a pixel's rgb value at x/y;
return a 24bit rgbValue (rrggbb, red is MSB),
or 32bit for alpha images (aarrggbb, alpha is MSB).
Pixels start at 0@0 for the upper left pixel,
and end at (width-1)@(height-1) for the lower right pixel.
rgbValueAtX: x y: y put: newRGBValue: expects a 24bit rgbValue (rrggbb, red is MSB),
or 32bit for alpha images (aarrggbb, alpha is MSB).
rowAt: y: retrieve an array filled with pixel values from a single row.
(eg. a horizontal span)
Notice: row/column coordinates start at 0.
The interpretation of the pixel values depends on the photometric.
This is a slow fallBack method, which works with any depth;
concrete image subclasses should redefine this for more performance.
rowAt: y into: aPixelBuffer: fill aBuffer with pixel values retrieved from a single row.
(eg. a horizontal span)
The interpretation of the pixel values depends on the photometric.
Notice: row/column coordinates start at 0.
rowAt: y into: aPixelBuffer startingAt: startIndex: fill aBuffer with pixel values retrieved from a single row.
(eg. a horizontal span)
The interpretation of the pixel values depends on the photometric.
Notice: row/column coordinates start at 0.
This is a slow fallBack method, which works with any depth;
concrete image subclasses should redefine this for more performance.
rowAt: y putAll: pixelArray: store a single row's pixels from bits in the argument;
(eg. a horizontal span)
The interpretation of the pixel values depends on the photometric.
Notice: row/column coordinates start at 0.
This is a slow fallBack method, which works with any depth;
concrete image subclasses should redefine this for more performance.
rowAt: y putAll: pixelArray startingAt: startIndex: store a single row's pixels from bits in the pixelArray argument;
(eg. a horizontal span)
The interpretation of the pixel values depends on the photometric.
Notice: row/column coordinates start at 0.
This is a slow fallBack method, which works with any depth;
concrete image subclasses should redefine this for more performance.
valueAt: aPoint: WARNING: for now, this returns a pixel's value
(backward compatibility with ST/X)
In the future, this will return a color (ST-80 compatibility)
Use #pixelAt: - for future compatibility.

Retrieve the pixelValue at aPoint; return an integer number.
Pixels start at 0@0 for upper left pixel, end at
width-1@height-1 for lower right pixel.
The returned numbers interpretation depends on the photometric
and the colormap. (see also Image>>at: and Image>>atX:y:)
You should not use this method for image-processing, its
very slow ...
(it is meant to access individual pixels - for example, in a bitmap editor)
valueAtX: x y: y: WARNING: for now, this returns a pixel's value
(backward compatibility with ST/X)
In the future, this will return a color (ST-80 compatibility)
Use #pixelAt: - for future compatibility.

Retrieve the pixelValue at aPoint; return an integer number.
Pixels start at 0/0 for upper left pixel, and end at
width-1@height-1 for lower right pixel.
The returned numbers interpretation depends on the photometric
and the colormap. (see also Image>>at: and Image>>atX:y:)
You should not use this method for image-processing of
big images, its very slow ...
(it is meant to access individual pixels - for example, in a bitmap editor)

accessing-private

bits: aByteArrayOrNil: set the raw pixel data.
With a nil argument, a pixel byte array of the correct size is allocated.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation
(it does not care for colormaps and/or cached device image flushing).
bits: aByteArrayArg colorMap: clrMapArg: set the raw data.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation
(it does not care for colormaps and/or cached device image flushing).
bits: aByteArrayArg colorMap: clrMapArg mask: maskArg: set the raw data.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation
(it does not care for colormaps and/or cached device image flushing).
bits: aByteArrayArg colorMapFromArray: clrMapArg: set the raw data.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation
(it does not care for colormaps and/or cached device image flushing).
bits: aByteArrayArg colorMapFromArray: clrMapArg mask: maskArg: set the raw data.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation
(it does not care for colormaps and/or cached device image flushing).
bits: aByteArrayArg mask: maskArg: set the raw data.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation
(it does not care for colormaps and/or cached device image flushing).
bitsPerSample: aCollection: set the number of bits per sample.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.
depth: d: set the depth of the image.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.
extent: anExtent: set the images extent.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.
hasAlphaChannel
height: aNumber: set the height of the image.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.
photometric: aSymbol: set the photometric interpretation of the pixel values.
The argument, aSymbol is one of:
#blackIs0, #whiteIs0, #palette, #rgb, #rgba
See TIFF documentation, from which the photometric concept is borrowed.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.
samplesPerPixel: aNumber: set the array of samples per pixel.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.
width: aNumber: set the width of the image.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.
width: w height: h: set the width and height of the image.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.
width: w height: h depth: d: set the width, height and depth of the image.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.
width: w height: h depth: d fromArray: bits: set the width, height, depth and pixels of the image.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.
width: w height: h depth: d palette: aColormap: set the width, height and depth of the image.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.
width: w height: h photometric: p: set the width, height and photometric of the image.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.
width: w height: h photometric: p samplesPerPixel: spp bitsPerSample: bps colorMap: cm bits: pixels: set all relevant internal state of the image.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.
width: w height: h photometric: p samplesPerPixel: spp bitsPerSample: bps colorMap: cm bits: pixels mask: m: set all relevant internal state of the image.

This interface is only to be used when initializing
instances or by image readers. Calling for a change of an
existing image may confuse later pixel interpretation.

comparing

= anImage
hash: Image fromScreen hash

conversion helpers

rgbColormapFor: aDevice: helper for conversion to rgb format

converting

anyImageAsTrueColorFormOn: aDevice

general fallback to return a true-color device-form for the receiver.

asFormOn: aDevice

get a device form, with best possible approximation.
remember it in case someone asks again.

asGrayFormOn: aDevice

get a gray device form

asGrayFormOn: aDevice dither: aDitherAlgorithm

get a greyscale device form, using aDitherAlgorithm.

asGrayImageDepth: depthArg

get a gray image from the receiver

asGrayImageDepth: depth dither: aDitherAlgorithm

get a greyscale image, using aDitherAlgorithm.

asImageWithDepth: depth

return a new image with another depth. Notice that this
may raise an error, if the depth is smaller than the receiver's depths
and the number of colors is greater than the number of possible colors
for the new depth - i.e. you should use this only to convert to a higher depth.
In the other case, use one of the dithering converters

asMonochromeFormOn: aDevice

get a monochrome device form

asMonochromeFormOn: aDevice dither: aDitherAlgorithm

get a monochrome device form, using aDitherAlgorithm.

asPseudoFormQuickOn: aDevice

return a pseudo-deviceForm from the image.
Fail if any color is not available (i.e. do not dither).

usage example(s):

     (
        (((Depth4Image
             width:4
             height:4
             fromArray:#[
                            16r01 16r23
                            16r45 16r67
                            16r89 16rab
                            16rcd 16ref
                        ]))
               magnifiedBy:30
         )
          asPseudoFormQuickOn:Display
      ) inspect

clearMaskedPixels

assuming that I already have a device representation
in deviceForm, clear any masked pixels.
This will allow faster drawing in the future.

exactOn: aDevice

for compatibility with color protocol - here, the same as #onDevice.

exactOrNearestOn: aDevice

for compatibility with color protocol - here, the same as #onDevice.

fromAlphaInImage: anImage

setup the receiver from the alpha channel of another image.
WARNING:
This implementation is a slow fallback (the loop over the
source pixels is very slow). If this method is used heavily, you
may want to redefine it in concrete subclasses for common source images.

fromForm: aForm

setup the receiver from a form

fromImage: anImage

setup the receiver from another image.
Color precision may be lost, if conversion is from a higher depth image.
WARNING:
This implementation is a slow fallback (the loop over the
source pixels is very slow). If this method is used heavily, you
may want to redefine it in concrete subclasses for common source images.

fromImage: anImage photometric: photometricOrNil

setup the receiver from another image and optionally set the photometric.
Color precision may be lost, if conversion is from a higher depth image.
WARNING:
This implementation is a slow fallback (the loop over the
source pixels is very slow). If this method is used heavily, you
may want to redefine it in concrete subclasses for common source images.

fromSubImage: anImage in: aRectangle

setup the receiver from another image, extracting a rectangular area.
As with layouts, the rectangle may contain integers (= nr of pixels) or float numbers (= relative size).
Color precision may be lost, if conversion is from a higher depth image.
For palette & rgb images, this may fail if a color cannot be represented.

fromSubImage: anImage inX: xL y: yT width: w height: h

setup the receiver from another image, extracting a rectangular area.
Color precision may be lost, if conversion is from a higher depth image.
For palette & rgb images, this may fail if a color cannot be represented.

WARNING:
This implementation is a slow fallback (the loop over the
source pixels is very slow). If this method is used heavily, you
may want to redefine it in concrete subclasses for the common case of
of creating a subImage with the same depth & palette.

monochromeOn: aDevice

return a monochrome device image of the receiver for aDevice.
(monochrome, even if device supports colors)

nearestOn: aDevice

for compatibility with color protocol - here, the same as #onDevice.

on: aDevice

return an image with the same pixels as the receiver, but
associated to aDevice. If the receiver is not yet bound to
a device, this will be the receiver. Otherwise, a new image
is returned.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

onDevice: aDevice

return an image with the same pixels as the receiver, but
associated to aDevice. If the receiver is not yet bound to
a device, this will be the receiver. Otherwise, a new image
is returned.

converting - dithering

asBurkesDitheredMonochromeImage

return a burkes dithered monochrome image from the receiver image.
Depending on the images contents, this may or may not look better than
a floyd-steinberg dithered image.
Notice that floyd-steinberg dithering is faster; both because less
error diffusion is done and due to being specially tuned.

asDitheredImageUsing: colors

return a dithered image from the picture,
using colors in colors for dithering.

asDitheredImageUsing: colors depth: d

return a dithered image from the picture,
using colors in colors for dithering.

asErrorDitheredMonochromeImage

return an error-diffusion dithered monochrome image from the receiver image.

asFloydSteinbergDitheredDepth8FormOn: aDevice colors: fixColors

return a floyd-steinberg dithered pseudoForm from the picture.
Use the colors in the fixColors array.
By passing the ditherColors as extra array, this method can
also be used to dither an 8bit image into a smaller number of colors,
for example to create dithered Depth4Images from Depth8Images.

asFloydSteinbergDitheredDepth8FormOn: aDevice colors: fixColors nRed: nRed nGreen: nGreen nBlue: nBlue

return a floyd-steinberg dithered pseudoForm from the palette picture.
Use the colors in the fixColors array, which must be fixR x fixG x fixB
colors assigned to aDevice, such as the preallocated colors of the
Color class.
By passing the ditherColors as extra array, this method can
also be used to dither an 8bit image into a smaller number of colors,
for example to create dithered Depth4Images from Depth8Images.

asFloydSteinbergDitheredGrayFormOn: aDevice

return a dithered depth-x grey form from the receiver image.

asFloydSteinbergDitheredGrayImageDepth: depth

return a floyd-steinberg dithered image from the receiver image.

asFloydSteinbergDitheredMonochromeFormOn: aDevice

return a dithered moncohrome form from the receiver image.

asFloydSteinbergDitheredMonochromeImage

return a floyd-steinberg dithered monochrome image from the receiver image.

asFloydSteinbergDitheredPseudoFormUsing: colors on: aDevice

return a floyd-steinberg dithered pseudoForm from the picture,
using colors in colors for dithering.

asOrderedDitheredGrayFormOn: aDevice

return a dithered depth-x grey form from the receiver image.
Uses an 8x8 dithermatrix.

asOrderedDitheredGrayImageDepth: depth

return a dithered depth-x grey image from the receiver image.
Uses an 8x8 dithermatrix.

asOrderedDitheredMonochromeFormOn: aDevice

return a dithered monochrome form from the grey image.
Uses a 4x4 dithermatrix.

asOrderedDitheredMonochromeFormOn: aDevice ditherMatrix: ditherMatrix ditherWidth: dW

return a dithered monochrome form from the image.
Uses the passed ditherMatrix and ditherWidth.

asOrderedDitheredMonochromeImage

return a dithered monochrome image from the receiver image.
Uses a 4x4 dithermatrix.

asOrderedDitheredMonochromeImageWithDitherMatrix: ditherMatrix ditherWidth: dW

return a dithered monochrome image from the receiver image.
Uses the passed ditherMatrix and ditherWidth.

usage example(s):

thresholding at:0.5 (all above 0.5 becomes white):

     |i|

     i := Image fromFile:'goodies/bitmaps/gifImages/garfield.gif'.
     i
        asOrderedDitheredMonochromeImageWithDitherMatrix:(ByteArray new:16 withAll:8)
        ditherWidth:4

usage example(s):

thresholding at: 0.25 (all above 0.25 becomes white):

     |i|

     i := Image fromFile:'goodies/bitmaps/gifImages/garfield.gif'.
     i
        asOrderedDitheredMonochromeImageWithDitherMatrix:(ByteArray new:16 withAll:3)
        ditherWidth:4

usage example(s):

thresholding at: 0.75 (all above 0.75 becomes white):

     |i|

     i := Image fromFile:'goodies/bitmaps/gifImages/garfield.gif'.
     i
        asOrderedDitheredMonochromeImageWithDitherMatrix:(ByteArray new:16 withAll:11)
        ditherWidth:4

asStevensonArceDitheredMonochromeImage

return a stevenson-arce dithered monochrome image from the receiver image.
Depending on the images contents, this may or may not look better than
a floyd-steinberg dithered image.
Notice that floyd-steinberg dithering is faster; both because less
error diffusion is done and due to being specially tuned.

converting - thresholding

asNearestPaintDepth8FormOn: aDevice colors: fixColors: return a nearest paint pseudoForm from the palette picture.
Use the colors in the fixColors array.
By passing the ditherColors as extra array, this method can
also be used to dither an 8bit image into a smaller number of colors,
for example to create dithered Depth4Images from Depth8Images.
asNearestPaintDepth8FormOn: aDevice colors: fixColors nRed: nRed nGreen: nGreen nBlue: nBlue: return a nearest paint pseudoForm from the palette picture.
Use the colors in the fixColors array, which must be fixR x fixG x fixB
colors assigned to aDevice, such as the preallocated colors of the
Color class.
By passing the ditherColors as extra array, this method can
also be used to dither an 8bit image into a smaller number of colors,
for example to create dithered Depth4Images from Depth8Images.
asNearestPaintImageDepth: d colors: colors: return a threshold image from the receiver picture, using colors in colors.
asThresholdGrayFormOn: aDevice: return a thresholded grey form from the receiver image.
asThresholdGrayImageDepth: depth: return a thresholded depth-x grey image from the receiver image.
asThresholdMonochromeFormOn: aDevice: return a threshold monochrome form from the image.
asThresholdMonochromeImage: return a threshold monochrome image from the image.
Threshold means: brightness < 0.5 -> black / otherwise white
asThresholdMonochromeImage: thresholdBrighness: return a threshold monochrome image from the image.
The argument (0..1) gives the threshold value;
Threshold means: brightness < threshold -> black / otherwise white

converting greyscale images

anyImageAsFormOn: aDevice: return a (usually truecolor) deviceForm from an arbitrary image.
anyImageAsPseudoFormOn: aDevice: return a (usually truecolor) deviceForm from an arbitrary image.

** This method raises an error - it must be redefined in concrete classes **
greyImageAsFormOn: aDevice: return a grey-deviceForm from the grey image.
greyImageAsPseudoFormOn: aDevice: return an 8-bit pseudo Form from the grey image
greyImageAsTrueColorFormOn: aDevice: return a true-color device-form for the grey-image receiver.
TODO: the pixel loops ought to be implemented as inline primitive code ...

converting palette images

paletteImageAsFormOn: aDevice: return a device-form for the palette-image receiver
paletteImageAsPseudoFormOn: aDevice: return a pseudo-deviceForm from the palette image.

** This method raises an error - it must be redefined in concrete classes **
paletteImageAsTrueColorFormOn: aDevice: return a true-color device-form for the palette-image receiver.

converting rgb images

asDitheredTrueColor8FormOn: aDevice

convert an rgb image to a dithered depth8-form on aDevice.
Return the device-form.
This method is only valid for trueColor displays.

compressColorMap

calculates a new color map for the image, using only used colors

copyPixels32AlphaHighTo24From: anImage

tuned helper to copy pixels from a 32bit rgba (alpha in high byte)
to me as a 24bit non-alpha rgb image

copyPixels32AlphaLowTo24From: anImage

tuned helper to copy pixels from a 32bit argb (alpha in low byte)
to me as a 24bit non-alpha rgb image

rgbImageAsFormOn: aDevice

convert am rgb image to a device-form on aDevice.
Return the device-form.

rgbImageAsPseudoFormOn: aDevice

return a pseudocolor form from the rgb-picture

** This method raises an error - it must be redefined in concrete classes **

rgbImageAsTrueColorFormOn: aDevice

return a truecolor form from the rgb-picture.

usage example(s):

'Image [warning]: unimplemented trueColor depth in rgbImageAsTrueColorFormOn: ' errorPrint. self bitsPerPixel errorPrintCR.

copying

skipInstvarIndexInDeepCopy: index: a helper for deepCopy; only indices for which this method returns
false are copied in a deep copy.

copying-private

postCopy: redefined to also copy the pixels and the colorMap
and clear out any device handles in the copy.

displaying

asImage: ST-80 compatibility
displayFilledOn: aGC: display the receiver as an opaque image.
This allows Images to be wrapped by a FillingWrapper
displayOn: aGCOrStream: draw the receiver in the graphicsContext, aGC.
Smalltalk-80 compatibility
displayOn: aGC x: x y: y: draw the receiver in the graphicsContext, aGC.
Smalltalk-80 compatibility
displayOn: aGC x: x y: y opaque: opaque: draw the receiver in the graphicsContext, aGC.
Smalltalk-80 compatibility
displayOpaqueOn: aGC at: aPoint: draw the receiver in the graphicsContext, aGC.
Smalltalk-80 compatibility
displayOpaqueOn: aGC x: x y: y: draw the receiver in the graphicsContext, aGC.
Smalltalk-80 compatibility
displayStrokedOn: aGC: display the receiver as an non opaque image.
This allows Images to be wrapped by a StrokingWrapper

dither helpers

burkesDitheredMonochromeBits: return the bitmap for a dithered monochrome bitmap from the image.
Works for any source depths / photometric.
TODO: move to separate dither helper class
floydSteinbergDitheredDepth8BitsColors: colors: return a floyd-steinberg dithered bitmap from the receiver picture,
which must be a depth-8 image.
This method expects an array of colors to be used for dithering
(which need not be a colorCubes colors).
floydSteinbergDitheredDepth8BitsColors: colors map: aMapOrNil: return a floyd-steinberg dithered bitmap from the receiver picture,
which must be a depth-24 image.
This method expects an array of colors to be used for dithering
(which need not be a colorCubes colors).
floydSteinbergDitheredDepth8BitsColors: fixColors nRed: nRed nGreen: nGreen nBlue: nBlue: return a floyd-steinberg dithered bitmap from the receiver picture,
which must be a depth-8 image.
This is a special-cased dither method for 8-bit palette images being displayed on
an 8-bit pseudoColor display, AND fixColor dithering is used.
Use the colors in the fixColors array, which must be fixR x fixG x fixB
colors assigned to aDevice, such as the preallocated colors of the
Color class.
By passing the ditherColors as extra array, this method can
also be used to dither an 8bit image into a smaller number of colors,
for example to create dithered Depth4Images from Depth8Images.
floydSteinbergDitheredGrayBitsDepth: depth: return the bits for dithering a gray image from the image.
Works for any source depths / photometric,
but possibly slow since each pixel is processed individually.
Redefined by some subclasses for more performance (D8Image/D24Image)
floydSteinbergDitheredMonochromeBits: return the bitmap for a dithered monochrome bitmap from the image.
Works for any source depths / photometric,
but very very slow since each pixel is processed individually.
Redefined by some subclasses for more performance (D8Image)
nearestPaintDepth8BitsColors: fixColors nRed: nRed nGreen: nGreen nBlue: nBlue: return a nearest paint bitmap from the receiver picture,
which must be a depth-8 image.
This is a special-cased dither method for 8-bit palette images being displayed on
an 8-bit pseudoColor display, AND fixColor dithering is used.
Use the colors in the fixColors array, which must be fixR x fixG x fixB
colors assigned to aDevice, such as the preallocated colors of the
Color class.
nfloydSteinbergDitheredDepth8BitsColors: colors: return a floyd-steinberg dithered bitmap from the receiver picture,
which must be a depth-8 image.
This method expects an array of colors to be used for dithering
(which need not be a colorCubes colors).
orderedDitheredGrayBitsDepth: depth: return the bitmap for a dithered depth-bitmap from the image
orderedDitheredGrayBitsWithDitherMatrix: ditherMatrix ditherWidth: dW depth: depth: return the bitmap for a dithered depth-bitmap from the image;
with a constant ditherMatrix, this can be used for thresholding.
Works for any source depths / photometric,
but very very slow since each pixel is processed individually.
Redefined by some subclasses for more performance (D8Image)
orderedDitheredMonochromeBits: return the bitmap for a dithered monochrome bitmap from the image;
using a default ditherMatrix.
orderedDitheredMonochromeBitsWithDitherMatrix: ditherMatrix ditherWidth: dW: return the bitmap for a dithered monochrome bitmap from the image;
with a constant ditherMatrix, this can be used for thresholding.
Works for any source depths / photometric,
but very very slow since each pixel is processed individually.
Redefined by some subclasses for more performance (D8Image)
stevensonArceDitheredMonochromeBits: return the bitmap for a dithered monochrome bitmap from the image.
Works for any source depths / photometric.
TODO: move to separate dither helper class

drawing

displayArcOrigin: origin corner: corner from: startAngle angle: angle withColor: aColor

draw part of a circle/ellipse with some pixel value.
By using a tempForm, we assure that the same pixel algorithm is used as in a window

displayArcOrigin: origin corner: corner from: startAngle angle: angle withValue: aPixelValueOrNil

draw part of a circle/ellipse with some pixel value.
By using a tempForm, we assure that the same pixel algorithm is used as in a window.
If aPixelValueOrNil is nil, the mask pixel will be set to 0 (transparent),
otherwise to 1. (used by the bitmap editor)

drawEllipse: aRectangle with: aColorOrPixelValue

draw a circle/ellipse with some pixel value or color.
By using a tempForm, we assure that the same pixel algorithm is used as in a window

drawEllipse: aRectangle withColor: aColor

draw a circle/ellipse with some pixel value.
By using a tempForm, we assure that the same pixel algorithm is used as in a window

drawEllipse: aRectangle withColor: aColor lineWidth: lw

draw a circle/ellipse with some pixel value.
By using a tempForm, we assure that the same pixel algorithm is used as in a window

drawEllipse: aRectangle withValue: aPixelValueOrNil

draw a circle/ellipse with some pixel value.
By using a tempForm, we assure that the same pixel algorithm is used as in a window.
If aPixelValueOrNil is nil, the mask pixel will be set to 0 (transparent),
otherwise to 1. (used by the bitmap editor)

drawEllipse: aRectangle withValue: aPixelValueOrNil lineWidth: lineWidthOrNil

drawLineFrom: startPoint to: endPoint with: aColorOrPixelValue

drawLineFrom: startPoint to: endPoint withColor: aColorOrPixelValue

drawLineFrom: startPoint to: endPoint withValue: aPixelValueOrNil

draw a line with some pixel value.
This is in no way tuned, as normally, display-forms are used to draw.
The only use for this is when we have to generate images in a headless webService
(such as the HumanReadableImageGenerator) or in the image editor.
If aPixelValueOrNil is nil, the mask pixel will be set to 0 (transparent),
otherwise to 1. (used by the bitmap editor)

drawRectangle: aRectangle with: aColorOrPixelValue

draw a rectangle with some pixel value.
By using #atImageAndMask:put: it also works on images with mono masks.

drawRectangle: aRectangle withColor: aColor

draw a rectangle with some pixel value.
By using #atImageAndMask:put: it also works on images with mono masks.

drawRectangle: aRectangle withValue: aPixelValueOrNil

draw a rectangle with some pixel value.
By using #atImageAndMask:put: it also works on images with mono masks.
If aPixelValueOrNil is nil, the mask pixel will be set to 0 (transparent),
otherwise to 1. (used by the bitmap editor)

fillAntiAliasedArc: origin radius: r from: startAngle angle: angle withColor: aColor colorDictionary: colorDictionary blendStart: blendStart

fill par tof an antialiased circle/ellipse with some pixel value.
By using a tempForm, we assure that the same pixel algorithm is used as in a window.
Compare the output of the example code at the end to the output from fillArc:radius:from:angle:withColor:

fillArc: origin radius: r from: startAngle angle: angle withColor: aColorOrIndex

fill part of a circle/ellipse with some pixel value.
By using a tempForm, we assure that the same pixel algorithm is used as in a window

fillEllipse: aRectangle with: aColorOrPixelValue

fill a circle/ellipse with some pixel value or color.
By using a tempForm, we assure that the same pixel algorithm is used as in a window

fillEllipse: aRectangle withColor: aColor

fill a circle/ellipse with some color.
By using a tempForm, we assure that the same pixel algorithm is used as in a window

fillEllipse: aRectangle withValue: aPixelValueOrNil

fill a circle/ellipse with some pixel value.
By using a tempForm, we assure that the same pixel algorithm is used as in a window.
If aPixelValueOrNil is nil, the mask pixel will be set to 0 (transparent),
otherwise to 1. (used by the bitmap editor)

fillRectangle: aRectangle with: aColorOrPixelValue

fill a rectangular area with some or pixel value.

fillRectangle: aRectangle withColor: aColor

fill a rectangular area with some color.

fillRectangle: aRectangle withValue: aPixelValueOrNil

fill a rectangular area with some pixel value.
May be redefined in concrete subclasses for more performance, if req'd.
If aPixelValueOrNil is nil, the mask pixel will be set to 0 (transparent),
otherwise to 1. (used by the bitmap editor)

fillRectangleX: x y: y width: w height: h with: aColorOrPixelValue

fill a rectangular area with a aColor

fillRectangleX: x y: y width: w height: h withColor: aColor

fill a rectangular area with a aColor

fillRectangleX: x y: y width: w height: h withValue: aPixelValueOrNil

fill a rectangular area with some pixel value.
May be redefined in concrete subclasses for more performance, if req'd.
If aPixelValueOrNil is nil, the mask pixel will be set to 0 (transparent),
otherwise to 1. (used by the bitmap editor)

floodFillAt: aPoint with: aColorOrPixelValue

fill a area with aColor like a flood up to surrounded pixels having different colors.
By using #atImageAndMask:put: it also works on images with mono masks.
Currently returns a collection of all pixels which have been modified (needed by imageEditor?),
but that should be changed to avoid huge massdata creation (instead, call a block for each)

floodFillAt: aPoint withColor: aColor

fill a area with aColor like a flood up to surrounded pixels having different colors.
By using #atImageAndMask:put: it also works on images with mono masks.
Currently returns a collection of all pixels which have been modified (needed by imageEditor?),
but that should be changed to avoid huge massdata creation (instead, call a block for each)

floodFillAt: aPoint withValue: aPixelValueOrNil

floodFillAt: aPoint withValue: aPixelValueOrNil maxDeviationInLight: maxLightError maxDeviationInHue: maxHueError

fill an area with aColor like a flood up to surrounded pixels having different colors.
If maxLightError/maxLueError are zero, the flood fills only pixels with the same value as the pixel at aPoint;
otherwise, a slight error (fraction) in light/hue is allowd, and pixels with a nearby color are also filled.
By using #atImageAndMask:put: it also works on images with mono masks.
Currently returns a collection of all pixels which have been modified (needed by imageEditor?),
but that should be changed to avoid huge massdata creation (instead, call a block for each)

usage example(s):

allDetectedPixelCoordinates := mask floodFillAt: aPoint withColor: Color white.

rectangle: aRectangle withColor: aColor

draw a rectangle with some pixel value.
By using #atImageAndMask:put: it also works on images with mono masks.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

enumerating

atY: y from: x1 to: x2 do: aBlock: perform aBlock for each pixel from x1 to x2 in row y.
The block is passed the color at each pixel.
The code here provides a generic and slow implementation, and
should be redefined in concrete subclasses, to avoid some processing
when going from pixel to pixel (i.e. the byte-index and mask computations
and also the color allocation).

** This is an obsolete interface - do not use it (it may vanish in future versions) **
colorsAtX: x from: y1 to: y2 do: aBlock: perform aBlock for each pixel from y1 to y2 in col x.
The block is passed the color at each pixel.
The code here provides a generic and slow implementation, and
should be redefined in concrete subclasses, to avoid some processing
when going from pixel to pixel (i.e. the byte-index and mask computations
and also the color allocation).
colorsAtY: y from: x1 to: x2 do: aBlock: perform aBlock for each pixel from x1 to x2 in row y.
The block is passed the color at each pixel.
The code here provides a generic and slow implementation, and
should be redefined in concrete subclasses, to avoid some processing
when going from pixel to pixel (i.e. the byte-index and mask computations
and also the color allocation).
colorsFromX: xStart y: yStart toX: xEnd y: yEnd do: aBlock: perform aBlock for each color in a rectangular area of the image.
Notice that x and y coordinates start at 0@0 for the upper left corner.
The block is passed the x and y coordinates and pixelValue at each pixel.
The code here provides a generic and slow implementation, and
should be redefined in concrete subclasses, to avoid some processing
when going from pixel to pixel (i.e. the byte-index and mask computations,
and especially, the color allocations).
rgbValuesAtY: y from: x1 to: x2 do: aBlock: perform aBlock for each rgbValue from x1 to x2 in row y.
rgbValues are of the form rrggbb (i.e. red is in the high byte).

Notice the difference between rgbValue and pixelValue: rgbValues are always
the rgb bytes; pixelvalues depend on the photometric interpretation, and may be
indices into a colormap or be non-byte-sized rgb values.

Notice that x and y coordinates start at 0@0 for the upper left corner.
The block is passed the x coordinate and the pixelValue at each pixel.
(see also Image>>atY:from:to:do:).
The code here provides a generic and slow implementation, and
should be redefined in concrete subclasses, to avoid some processing
when going from pixel to pixel (i.e. the byte-index and mask computations).
rgbValuesFromX: xStart y: yStart toX: xEnd y: yEnd do: aBlock: perform aBlock for each rgbValue in a rectangular area of the image.
rgbValues are of the form rrggbb (i.e. the redByte is in the high byte).

Notice the difference between rgbValue and pixelValue: rgbValues are always
the rgb bytes; pixelvalues depend on the photometric interpretation, and may be
indices into a colormap or be non-byte-sized rgb values.

Notice that x and y coordinates start at 0@0 for the upper left corner.
The block is passed the x and y coordinates and pixelValue at each pixel.
The code here provides a generic and slow implementation, and
should be redefined in concrete subclasses, to avoid some processing
when going from pixel to pixel (i.e. the byte-index and mask computations).
valueAtY: y from: x1 to: x2 do: aBlock: perform aBlock for each pixelValue from x1 to x2 in row y.
Obsolete - remains for backward compatibility.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
valuesAtY: y from: x1 to: x2 do: aBlock: WARNING: this enumerates pixel values which need photometric interpretation
Do not confuse with #rgbValuesAtY:from:to:do:

Perform aBlock for each pixelValue from x1 to x2 in row y.

Notice the difference between rgbValue and pixelValue: rgbValues are always
the rgb bytes; pixelvalues depend on the photometric interpretation, and may be
indices into a colormap or be non-byte-sized rgb values.

Notice that x and y coordinates start at 0@0 for the upper left corner.
The block is passed the x coordinate and the pixelValue at each pixel.
(see also Image>>atY:from:to:do:).
The code here provides a generic and slow implementation, and
should be redefined in concrete subclasses, to avoid some processing
when going from pixel to pixel (i.e. the byte-index and mask computations).
valuesFromX: xStart y: yStart toX: xEnd y: yEnd do: aBlock: WARNING: this enumerates pixel values which need photometric interpretation
Do not confuse with #rgbValuesAtY:from:to:do:

Perform aBlock for each pixelValue in a rectangular area of the image.

Notice the difference between rgbValue and pixelValue: rgbValues are always
the rgb bytes; pixelvalues depend on the photometric interpretation, and may be
indices into a colormap or be non-byte-sized rgb values.

Notice that x and y coordinates start at 0@0 for the upper left corner.
The block is passed the x and y coordinates and pixelValue at each pixel.
The code here provides a generic and slow implementation, and
should be redefined in concrete subclasses, to avoid some processing
when going from pixel to pixel (i.e. the byte-index and mask computations).

finalization

finalizationLobby: answer the registry used for finalization.
Images have their own Registry
finalize: some Image has been collected - nothing to do.

The only reason we register Images is, that we can release
their device resources when a GraphicsDevice is closed.

(#releaseResourcesOnDevice: at class side).

image manipulations

applyPixelValuesTo: pixelFunctionBlock in: aRectangle into: newImage

helper for withPixelFunctionAppliedToValues:
enumerate pixelValues and evaluate the block for each.
Could be redefined by subclasses for better performance.

applyPixelValuesTo: pixelFunctionBlock into: newImage

helper for withPixelFunctionAppliedToValues:
enumerate pixelValues and evaluate the block for each.

blendWith: aColor

return a new image which is blended with some color.
The receiver must be a palette image (currently).
CAVEAT: this only works with palette images (i.e. not for rgb or greyScale).
CAVEAT: Need an argument, which specifies by how much it should be lighter.

usage example(s):

     (Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') inspect
     ((Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') blendWith:Color red) inspect
     ((Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') blendWith:Color white) inspect
     ((Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') blendWith:Color black) inspect

colorMapProcessing: aBlock

a helper for all kinds of colormap manipulations.
The argument, aBlock is called for every colormap entry,
and the returned value will replace the original entry in the map.
For non-palette images, aBlock is called for every pixel value
(instead of colormap values), and the returned color is stored back
into the image).
See examples in Image>>copyWithColorMapProcessing:

copyWithColorMapProcessing: aBlock

a helper to create & return new images based on the receiver with
some colorMap processing. The receiver is copied, and the copied images
colormap is modified by replacing entries with the result of the processing block,
which is called with the original color values.
The block is supposed to return a color.
CAVEAT: this only works with palette images (i.e. not for rgb or greyScale)

usage example(s):

     leave red component only:

     (Image fromFile:'goodies/bitmaps/gifImages/claus.gif')
        copyWithColorMapProcessing:[:clr | Color red:(clr red) green:0 blue:0]

usage example(s):

     make it reddish:

     (Image fromFile:'../../goodies/bitmaps/gifImages/claus.gif')
        copyWithColorMapProcessing:[:clr | Color red:((clr red * 2) min:100) green:clr green blue:clr blue]

createMask

create a mask filled with ones (i.e. all pixels opaque)

createMaskForPixelValue: pixelValue

create or modify the mask to be off wherever the pixelValue appears.
If there is already a mask, pixels which are already masked remain so.
This is a helper for image readers which use a pixel index as mask,
instead of a separate mask plane.

This is a slow fallback, if it turns out to be timing relevant,
redefine in concrete image classes (especially Depth8Image)

darkened

return a new image which is slightly darker than the receiver.
The receiver must be a palette image (currently).
CAVEAT: this only works with palette images (i.e. not for rgb or greyScale).
CAVEAT: Need an argument, which specifies by how much it should be darker.

usage example(s):

     (Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') inspect
     (Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') darkened inspect

easyRotateBitsInto: destinationImage angle: degrees

helper for rotation - does the actual pixel shuffling.
by degrees clockwise. Here, only 90, 180 and 270 degrees
are implemented. Hard angles are done in #hardRotate:.
The code here is depth-independent (but not too fast);
can be redefined in subclasses for more performance

flipHorizontal

destructively inplace horizontal flip

usage example(s):

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

flipVertical

inplace vertical flip

usage example(s):

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

hardAntiAliasedMagnifiedBy: scalePoint

return a new image magnified and antiAliased by scalePoint, aPoint.
This converts into a depth24Image before doing the antiAlias-magnify.
It is definitely slower than the non antiAliasing/integral magnification methods.

hardMagnifiedBy: scaleArg

return a new image magnified by scalePoint, aPoint.
This is the general magnification method, handling non-integral values.
It is slower than the integral magnification method.

Notice: this is a naive algorithm, which simply samples the pixel value
at the corresponding original pixel's point, without taking neighbors into
consideration (i.e. it does not compute an average of those pixels).
As a consequence, this will generate bad shrunk images when the original contains
sharp lines.

hardMagnifiedBy: scaleArg smooth: smoothBoolean

return a new image magnified by scalePoint, aPoint.
This is the general magnification method, handling non-integral values.
It is slower than the integral magnification method.

If smoothBoolean is true, an improved algorithm is used,
which averages the pixels if shrinking or interpolates if expanding
(i.e. it smoothens when resampling) and this should generate nicer shrunk
images when the original contains sharp lines.

If it is false, a naive subsampling is performed, which is much faster,
but produces ugly magnifications (and especially: ugly shrunk versions)

hardRotated: degrees

return a new image from the old one, by rotating the image
degrees clockwise (around its center).
Warning: the returned image will be larger than the original image.

hardSmoothingMagnifiedBy: scaleArg

return a new image magnified by scalePoint, aPoint.
This is the general magnification method, handling non-integral values.
It is slower than the integral magnification method,
and slower than the old hardMagnifiedBy: method.

Notice: this is an improved algorithm, which averages the pixels if shrinking
or interpolates if expanding.
As a consequence, this should generate nicer shrunk images when the original contains sharp lines.

lightened

return a new image which is slightly brighter than the receiver.
The receiver must be a palette image (currently).
CAVEAT: this only works with palette images (i.e. not for rgb or greyScale).
CAVEAT: Need an argument, which specifies by how much it should be lighter.

usage example(s):

     (Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') inspect
     (Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') lightened inspect
     (Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') darkened inspect
     (Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') darkened darkened inspect

magnifiedBy: scale

return a new image magnified by scalePoint, aPoint.
If non-integral magnify is asked for, pass the work on to 'hardMagnifyBy:'
while simple (integral) magnifications are handled here.

usage example(s):

     (Image fromFile:'../../goodies/bitmaps/gifImages/claus.gif') inspect.
     ((Image fromFile:'../../goodies/bitmaps/gifImages/claus.gif') magnifiedBy:1@2) inspect.

magnifiedBy: scale smooth: smooth

return a new image magnified by scalePoint, aPoint.
If non-integral magnify is asked for, pass the work on to 'hardMagnifyBy:'
while simple (integral) magnifications are handled here.

usage example(s):

     ((Image fromFile:'goodies/bitmaps/gifImages/claus.gif') magnifiedBy:1@2)

magnifiedPreservingRatioTo: anExtent

return a new image magnified to fit into anExtent,
preserving the receiver's width/height ratio.
(i.e. not distorting the image).
See also #magnifiedTo: and #magnifiedBy:

usage example(s):

     ((Image fromFile:'../../goodies/bitmaps/gifImages/garfield.gif') magnifiedPreservingRatioTo:100@100)

    in contrast to:

     ((Image fromFile:'../../goodies/bitmaps/gifImages/garfield.gif') magnifiedTo:100@100)

magnifiedPreservingRatioTo: anExtent smooth: smoothBoolean

return a new image magnified to fit into anExtent,
preserving the receiver's width/height ratio.
(i.e. not distorting the image).
See also #magnifiedTo: and #magnifiedBy:

usage example(s):

     ((Image fromFile:'../../goodies/bitmaps/gifImages/garfield.gif') magnifiedPreservingRatioTo:100@100)

    in contrast to:

     ((Image fromFile:'../../goodies/bitmaps/gifImages/garfield.gif') magnifiedTo:100@100)

magnifiedTo: anExtent

return a new image magnified to have the size specified by extent.
This may distort the image if the arguments ratio is not the images ratio.
See also #magnifiedPreservingRatioTo: and #magnifiedBy:

usage example(s):

     ((Image fromFile:'goodies/bitmaps/gifImages/garfield.gif') magnifiedTo:100@100)

    in contrast to:

     ((Image fromFile:'goodies/bitmaps/gifImages/garfield.gif') magnifiedPreservingRatioTo:100@100)

magnifiedTo: anExtent smooth: aBoolean

return a new image magnified to have the size specified by extent.
This may distort the image if the arguments ratio is not the images ratio.
See also #magnifiedPreservingRatioTo: and #magnifiedBy:

usage example(s):

     (Image fromFile:'../../goodies/bitmaps/gifImages/garfield.gif') magnifiedTo:100@100 smooth:true

    in contrast to:

     (Image fromFile:'../../goodies/bitmaps/gifImages/garfield.gif') magnifiedTo:100@100 smooth:false

    and:
     ((Image fromFile:'../../goodies/bitmaps/gifImages/garfield.gif') magnifiedPreservingRatioTo:100@100)
    and:
     ((Image fromFile:'../../goodies/bitmaps/gifImages/garfield.gif') magnifiedPreservingRatioTo:100@100 smooth:true)

mixed: amount with: aColor

return a new image which is blended with some color;
amount determines how much of the blending color is applied (0..)
where 0 means: blending color pure.
The receiver must be a palette image (currently).
CAVEAT: this only works with palette images (i.e. not for rgb or greyScale).
CAVEAT: Need an argument, which specifies by how much it should be lighter.

usage example(s):

     (Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') inspect
     ((Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') mixed:0.0 with:Color red) inspect
     ((Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') mixed:0.1 with:Color red) inspect
     ((Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') mixed:0.25 with:Color red) inspect
     ((Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') mixed:0.5 with:Color red) inspect
     ((Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') mixed:1 with:Color red) inspect
     ((Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') mixed:2 with:Color red) inspect
     ((Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') mixed:10 with:Color red) inspect
     ((Smalltalk bitmapFromFileNamed:'gifImages/claus.gif' inPackage:'stx:goodies') mixed:20 with:Color red) inspect

negative

return a new image which is a negative of the receiver.
The receiver must be a palette image (currently).

usage example(s):

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

rotated: degrees

return a new image from the old one, by rotating the image degrees clockwise.
Notice that the resulting image has a different extent.
If rotation is heavily used, the workHorse methods
(#easyRotateBitsInto:angle: and #hardRotated:) may
be redefined in concrete image subclasses.

slightlyDarkened

slightlyLightened

smoothingMagnifiedBy: scale

return a new image magnified by scalePoint, aPoint.
If non-integral magnify is asked for, pass the work on to 'hardMagnifyBy:'
while simple (integral) magnifications are handled here.

smoothingMagnifiedPreservingRatioTo: anExtent

return a new image magnified to fit into anExtent,
preserving the receiver's width/height ratio.
(i.e. not distorting the image).
See also #magnifiedTo: and #magnifiedBy:

threeDProjected: fraction1 and: fraction2

return a 3D-projected version.
Not really 3D, but good enough to create screenshots for webpages...
TODO: kick out this q&d hack, and write something real...

withColorResolutionReducedBy: numBits

return a new image with the same picture as the receiver,
but reduced colorResolution.
That is, the lower numBits are cleared in the r/g/b color components.
If anything fails, return nil.

withPixelFunctionApplied: pixelFunctionBlock

return a new image from the old one,
by applying a pixel processor on the pixel colors.

Notice: this method is relatively slow - either apply pixel values
(#withPixelFunctionAppliedToPixels:) or redefine this method in
a concrete subclass.
(read `Beyond photography, by Gerard J. Holzmann;
ISBM 0-13-074410-7)
See blurred / oilPainted as examples ...)

withPixelFunctionAppliedToPixels: pixelFunctionBlock

return a new image from the old one, by applying a pixel processor
on the pixel values.
(read `Beyond photography, by Gerard J. Holzmann;
ISBM 0-13-074410-7)
See blurred / oilPainted as examples ...)

withPixelFunctionAppliedToPixels: pixelFunctionBlock in: aRectangle

return a new image from the old one, by applying a pixel processor
on the pixel values.
(read `Beyond photography, by Gerard J. Holzmann;
ISBM 0-13-074410-7)
See blurred / oilPainted as examples ...)

initialization

createPixelStore: instantiate the underlying pixel storage (a byteArray)
initialize

inspecting

inspector2TabImage
( an extension from the stx:libtool package ): an extra tab showing the image;
Q: is this needed? (the displayObject tab already shows this)
inspector2TabImageCreatorClass
( an extension from the stx:libtool package ): ToolbarIconLibrary systemBrowserIcon inspect
inspector2Tabs
( an extension from the stx:libtool package ): (comment from inherited method)
a collection of tabs to show in the new inspector;
redefined by many to add more tabs (bitmap, hexDump, color, etc.)
inspectorExtraAttributes
( an extension from the stx:libtool package ): ToolbarIconLibrary systemBrowserIcon inspect
inspectorExtraMenuOperations
( an extension from the stx:libtool package )

instance release

close: release device resources; destroy any device-resources
release: release device resources
releaseFromDevice: release device resources
restored: flush device specifics after a snapin or binary restore.
Also to flush any cached device forms, after drawing into the pixel store

misc ui support

inspectorClass
( an extension from the stx:libtool package ): redefined to launch an ImageInspector
(instead of the default InspectorView).

obsolete

applyPixelValuesTo: pixelFunctionBlock into: newImage in: aRectangle: helper for withPixelFunctionAppliedToValues:
enumerate pixelValues and evaluate the block for each.
To be redefined by subclasses for better performance.
magnifyBy: scale: obsolete: has been renamed to magnifiedBy: for ST-80 compatibility
and name consistency ...

** This is an obsolete interface - do not use it (it may vanish in future versions) **

pixel copying

bitBltFrom: anImage function: function x: srcX y: srcY toX: dstX y: dstY width: w height: h: operates on pixel values.
Any mask is left unchanged.

WARNING:
This is a q@d hack to support the minimum needed for the QRCode generator.

This implementation is a very slow fallback general algorithm
(the loop over the source pixels is very slow).
If this method is used heavily, you may want to redefine it in
concrete subclasses for the common case of of copying from an Image
with the same depth & palette.
If you do heavy image processing, specialized versions are even req'd
for other cases, rewriting the inner loops as inline C-code.
copyFrom: anImage x: srcX y: srcY toX: dstX y: dstY width: w height: h: replace a rectangular area by pixels from another image.
The source's colors must be present in the destination's
colorMap - otherwise, an error will be reported.
Any mask is copied from the source.

WARNING:
This implementation is a very slow fallback general algorithm
(the loop over the source pixels is very slow).
If this method is used heavily, you may want to redefine it in
concrete subclasses for the common case of of copying from an Image
with the same depth & palette.
If you do heavy image processing, specialized versions are even req'd
for other cases, rewriting the inner loops as inline C-code.
copyFrom: anImage x: srcX y: srcY toX: dstX y: dstY width: w height: h masked: maskedCopy: replace a rectangular area by pixels from another image.
The sources colors must be present in the destinations
colorMap - otherwise, an error will be reported.

WARNING:
This implementation is a very slow fallback general algorithm
(the loop over the source pixels is very slow).
If this method is used heavily, you may want to redefine it in
concrete subclasses for the common case of of copying from an Image
with the same depth & palette.
If you do heavy image processing, specialized versions are even req'd
for other cases, rewriting the inner loops as inline C-code.
copyMaskedFrom: anImage x: srcX y: srcY toX: dstX y: dstY width: w height: h: replace a rectangular area by pixels from another image.
The sources colors must be present in the destinations
colorMap - otherwise, an error will be reported.
Only unmasked pixels are copied from the source.

WARNING:
This implementation is a very slow fallback general algorithm
(the loop over the source pixels is very slow).
If this method is used heavily, you may want to redefine it in
concrete subclasses for the common case of of copying from an Image
with the same depth & palette.
If you do heavy image processing, specialized versions are even req'd
for other cases, rewriting the inner loops as inline C-code.
subImageIn: aRectangle: create and return a new image consisting of a subArea of myself

pixel functions

computeBitsFromPixelFunction: compute the bits from the pixelfunction
pixelFunction
pixelFunction: aTwoArgFunction: set the pixel function. This is used to define a functional image,
where pixel values are computed via a function instead of coming
from a bits array (although a pixel array could also be seen as
a pixel function).
The pixelFunction will map (x E [0 .. width]) x (y E [0 .. height]) -> pixel
pixelFunction: aTwoArgFunction inX: xInterval y: yInterval: set the pixel function and a viewport.
This is used to define a functional image,
where pixel values are computed via a function instead of coming
from a bits array.
The pixelFunction will map (x E xInterval) x (y E yInterval) -> pixel

printing & storing

storeOn: aStream: append a printed representation of the receiver to aStream,
from which a copy of it can be reconstructed.

private

bestSupportedImageFormatFor: aDevice

scan through the image formats as supported by aDevice,
and return the best to use when the receiver is to be represented
on it. The best format is the one with the same number or more bits per
pixel. Here, the smallest format found which can represent enough pixels is taken.

colormapFromImage: anImage

setup the receiver's colormap from another image.
Color precision may be lost, if conversion is from a higher depth
image. This does not convert any pixel values; it is non-public helper
for fromImage:/fromSubImake:

colormapFromImage: anImage photometric: photometricOrNil

fromDeviceForm: aForm maskForm: aMaskFormOrNil

greyByteMapForRange: range

return a collection to map from pixelValues to greyLevels
in the range 0..range.
Range must be < 256 (for elements to fit into a ByteArray).
The values are rounded towards the nearest pixel.

usage example(s):

     Depth8Image new greyByteMapForRange:256

     Depth8Image new greyByteMapForRange:64
     Depth4Image new greyByteMapForRange:64

     Depth4Image new greyByteMapForRange:1

greyMapForRange: range

return a collection to map from pixelValues to greyLevels
in the range 0..range. The brightness values are not rounded.

usage example(s):

     Depth8Image new greyMapForRange:64
     Depth4Image new greyMapForRange:64

     Depth16Image new greyMapForRange:1
     Depth4Image new greyMapForRange:1
     Depth2Image new greyMapForRange:1

magnifyRowFrom: srcBytes offset: srcStart into: dstBytes offset: dstStart factor: mX

magnify a single pixel row - can only magnify by integer factors,
can only magnify 1,2,4,8 and 24 bit-per-pixel images. But this is done fast.

** This method raises an error - it must be redefined in concrete classes **

makeDeviceGrayPixmapOn: aDevice depth: depth fromArray: bits

given the bits of a grey/color bitmap, 8-bit padded and
pixels interpreted as greyValues, 0 is black,
create a device form for it

makeDeviceMonochromeBitmapOn: aDevice fromArray: monoBits

given the bits of a monochrome bitmap, 8-bit padded and
0-bits as black, create a device form for it

makeDevicePixmapOn: aDevice depth: depth fromArray: bits

given the bits of a grey/color bitmap, 8-bit padded and
pixels interpreted as in the devices colormap,
create a device form for it

repairPhotometric

kludge: repair a 'should not happen' situation...

queries

alphaBitsOf: pixel

if the receiver is an rgb-image:
return the alpha component of a pixelValue as integer 0..maxAlphaValue.
MaxAlphaValue is of course the largest integer representable by the number
of alpha bits i.e. (1 bitShift:bitsAlpha)-1.
This has to be redefined by subclasses.

** This method raises an error - it must be redefined in concrete classes **

alphaMaskForPixelValue

return the mask used with translation from pixelValues to alphaBits

** This method raises an error - it must be redefined in concrete classes **

alphaShiftForPixelValue

return the shift amount used with translation from pixelValues to alphaBits.
That is the number of bits to shift the alpha value into the pixel value.

** This method raises an error - it must be redefined in concrete classes **

ascentOn: aGC

I will not draw myself above the baseline

averageColor

return the average color of the image.
This usually only makes sense for textures and patterns
(i.e. to compute shadow & light colors for viewBackgrounds).
Notice that for the above purpose, it is usually ok to process
a subImage - i.e. use Image>>averageColorIn: on a smaller rectangle

averageColorIn: aRectangle

return the images average color in an area.
The implementation below is slow - so you may want to
create tuned versions for DepthXImage if you plan to do
heavy image processing ...
(also, creating tuned versions of the enumeration messages helps a lot)

bitsPerPixel

return the number of bits per pixel

bitsPerRow

return the number of bits in one scanline of the image

blackComponentOfCMYK: pixel

if the receiver is a cmyk-image:
return the black component scaled to a percentage (0 .. 100) of a pixelValue.

** This method raises an error - it must be redefined in concrete classes **

blueBitsOf: pixel

if the receiver is an rgb-image:
return the blue bits of a pixelValue as integer 0..maxBlueValue.
MaxGreenValue is of course the largest integer representable by the number
of blue bits i.e. (1 bitShift:bitsBlue)-1.
This has to be redefined by subclasses.

** This method raises an error - it must be redefined in concrete classes **

blueComponentOf: pixel

if the receiver is an rgb-image:
return the blue component scaled to a percentage (0 .. 100) of a pixelValue.
This has to be redefined by subclasses.

** This method raises an error - it must be redefined in concrete classes **

blueMaskForPixelValue

return the mask used with translation from pixelValues to blueBits

** This method raises an error - it must be redefined in concrete classes **

blueShiftForPixelValue

return the shift amount used with translation from pixelValues to blueBits

** This method raises an error - it must be redefined in concrete classes **

bounds

return my bounds (added to make images usable as VisualComponents)

brightness

return the (average) brightness of the image as number in 0..1.
This usually only makes sense for textures and patterns
(i.e. to compute shadow & light colors for viewBackgrounds).
Notice that for the above purpose, only a subimage is inspected here

bytesPerRow

return the number of bytes in one scanline of the image

bytesPerRowPaddedTo: padding

return the number of bytes in one scanline of the image,
if scanlines are to be padded to padding-bits.

center

for compatibility with GC protocol - return the centerPoint

chromaBlueOfYCbCr: pixel

if the receiver is an YCbCr-image:
return the blue-chroma (Cb) component, scaled to (0 .. 1)

** This method raises an error - it must be redefined in concrete classes **

chromaRedOfYCbCr: pixel

if the receiver is an YCbCr-image:
return the red-chroma (Cr) component, scaled to (0 .. 1)

** This method raises an error - it must be redefined in concrete classes **

colorFromValue: pixelValue

given a pixel value, return the corresponding color.
Pixel values start with 0.
The implementation below is generic and slow
- this method is typically redefined in subclasses.

cyanComponentOfCMY: pixel

if the receiver is a cmy-image:
return the cyan component scaled to a percentage (0 .. 100) of a pixelValue.

** This method raises an error - it must be redefined in concrete classes **

cyanComponentOfCMYK: pixel

if the receiver is a cmyk-image:
return the cyan component scaled to a percentage (0 .. 100) of a pixelValue.

** This method raises an error - it must be redefined in concrete classes **

greenBitsOf: pixel

if the receiver is an rgb-image:
return the green bits of a pixelValue as integer 0..maxGreenValue.
MaxGreenValue is of course the largest integer representable by the number
of green bits i.e. (1 bitShift:bitsGreen)-1.
This has to be redefined by subclasses.

** This method raises an error - it must be redefined in concrete classes **

greenComponentOf: pixel

if the receiver is an rgb-image:
return the green component scaled to a percentage (0..100) of a pixelValue.
This has to be redefined by subclasses.

** This method raises an error - it must be redefined in concrete classes **

greenMaskForPixelValue

return the mask used with translation from pixelValues to greenBits

** This method raises an error - it must be redefined in concrete classes **

greenShiftForPixelValue

return the shift amount used with translation from pixelValues to greenBits

** This method raises an error - it must be redefined in concrete classes **

heightOn: aGC

return my height, if displayed on aGC;
since my height is independent of the device (the number of pixels),
return the pixel-height

isDithered

for compatibility with color protocol

isGrayscaleImage

isImage

return true, if the receiver is some kind of image;
true is returned here - the method is redefined from Object.

isImageOrForm

return true, if the receiver is some kind of image or form;
true is returned here - the method is redefined from Object.

isMask

lumaOfYCbCr: pixel

if the receiver is an YCbCr-image:
return the luma (Y) component, scaled to (0 .. 1)

** This method raises an error - it must be redefined in concrete classes **

magentaComponentOfCMY: pixel

if the receiver is a cmy-image:
return the magenta component scaled to a percentage (0 .. 100) of a pixelValue.

** This method raises an error - it must be redefined in concrete classes **

magentaComponentOfCMYK: pixel

if the receiver is a cmyk-image:
return the magenta component scaled to a percentage (0 .. 100) of a pixelValue.

** This method raises an error - it must be redefined in concrete classes **

nColorsUsed

numAlphaBits

alpha in low bits

numBlueBits

alpha in low bits

** This method raises an error - it must be redefined in concrete classes **

numGreenBits

alpha in low bits

** This method raises an error - it must be redefined in concrete classes **

numRedBits

alpha in low bits

** This method raises an error - it must be redefined in concrete classes **

pixelArraySpecies

return the kind of pixel-value container in rowAt:/rowAt:put: methods

realColorMap

return a collection usable as a real colormap of the image.
For palette images, this is the internal colormap;
for other photometrics (which do not have a real colormap), synthesize one.
This is different from #colorMap, which returns nil for non palette images.

realUsedColors

return a collection of colors which are really used in the receiver.
This goes through the pixels and adds up colors as present in the image
(as opposed to #usedColors, which looks at the colorMap if present)

realUsedValues

return a collection of color values used in the receiver.
Notice that the interpretation of the pixels depends on the photometric
of the image.
This is a general and therefore slow implementation; subclasses
may want to redefine this method for more performance.
This goes through the pixels and adds up colors as present in the image
(as opposed to #usedColors, which looks at the colorMap if present)

redBitsOf: pixel

if the receiver is an rgb-image:
return the red component of a pixelValue as integer 0..maxRedValue.
MaxRedValue is the largest integer representable by the number
of red bits i.e. (1 bitShift:bitsRed)-1.
This has to be redefined by subclasses.

** This method raises an error - it must be redefined in concrete classes **

redComponentOf: pixel

if the receiver is an rgb-image:
return the red component scaled to a percentage (0..100) of a pixelValue.
This has to be redefined by subclasses.

** This method raises an error - it must be redefined in concrete classes **

redMaskForPixelValue

return the mask used with translation from pixelValues to redBits

** This method raises an error - it must be redefined in concrete classes **

redShiftForPixelValue

return the shift amount used with translation from pixelValues to redBits

** This method raises an error - it must be redefined in concrete classes **

rgbFromValue: pixelValue

given a pixel value, return the corresponding 24bit rgbValue (rrggbb, red is MSB).
Pixel value is in 0..2^depth - 1.
The implementation below is generic and slow
- this method is typically redefined in subclasses.

usage example(s):

     (self basicNew
        bitsPerSample:#(8 8 8);
        photometric:#YCbCr;
        samplesPerPixel:3;
        yourself
     ) rgbFromValue: 16r7F1010

     (self basicNew
        bitsPerSample:#(8 8 8);
        photometric:#YCbCr;
        samplesPerPixel:3;
        yourself
     ) rgbFromValue: 16rFF1010

     (self basicNew
        bitsPerSample:#(8 8 8);
        photometric:#YCbCr;
        samplesPerPixel:3;
        yourself
     ) rgbFromValue: 16rFF0000

usedColors

return a collection of colors used in the receiver.
This looks at the colorMap only if present.
(as opposed to #realUsedColors, which goes through the pixels of the bitmap)

usage example(s):

     (Image fromFile:'goodies/bitmaps/gifImages/garfield.gif') usedColors
     (Image fromFile:'libtool/bitmaps/SBrowser.xbm') usedColors

usedColorsMax: nMax

return a collection of colors used in the receiver;
This looks at the colorMap only if present
(as opposed to #realUsedColors, which goes through the pixels of the bitmap).
However, stop looking for more, if more than nMax colors have been found
(useful when searching rgb images).

usedValues

usage example(s):

     (Image fromFile:'goodies/bitmaps/gifImages/garfield.gif') usedValues
     (Image fromFile:'lib tool/bitmaps/SBrowser.xbm') usedValues

valueFromColor: color

given a color, return the corresponding pixel value.
Non-representable colors return nil.

valueFromRGB: rgb

given a color as rgb-value, with 8 bits per component,
return the corresponding pixel value.
The red component is in the high 8 bits.
Non-representable colors return nil.

valueFromRedBits: redBits greenBits: greenBits blueBits: blueBits

given the rgb bits, each in 0..maxXXXValue (i.e. according to
r/g/b channels number of bits, return the corresponding pixel value.
For now, only useful with RGB images

widthOn: aGC

return my width, if displayed on aGC;
since my width is independent of the device (the number of pixels),
return the pixel-width

yellowComponentOfCMY: pixel

if the receiver is a cmy-image:
return the yellow component scaled to a percentage (0 .. 100) of a pixelValue.

** This method raises an error - it must be redefined in concrete classes **

yellowComponentOfCMYK: pixel

if the receiver is a cmyk-image:
return the yellow component scaled to a percentage (0 .. 100) of a pixelValue.

** This method raises an error - it must be redefined in concrete classes **

saving on file

bytesForFileUsing: readerClass: return the contents of a file if saved by readerClass.
That is: an imageWriter is created to generate the bytes
as if written to a file.
No actual file is created, but the bytes are returned
saveOn: aFileName: save the image in aFileName. The suffix of the filename controls the format.
Currently, not all formats may be supported
(see ImageReader subclasses implementing save:onFile:).
May raise a signal, if the image cannot be written by the reader.
saveOn: aFileName quality: qualityPercentOrNil: save the image in aFileName. The suffix of the filename controls the format.
Currently, not all formats may be supported
(see ImageReader subclasses implementing save:onFile:).
May raise a signal, if the image cannot be written by the reader.
saveOn: aFileName quality: qualityPercentOrNil using: readerClass: save the receiver using the representation class
(which is usually a concrete subclasses of ImageReader).
May raise a signal, if the image cannot be written by the reader.
saveOn: aFileName using: readerClass: save the receiver using the representation class
(which is usually a concrete subclasses of ImageReader).
May raise a signal, if the image cannot be written by the reader.

screen capture

from: aDrawable in: aRectangle

read an image from aDrawable.
This may be a device Form, a view or the rootView.
If it's a view or rootView, it must be completely visible (or have
the backingStore option turned on). Otherwise, only the clipped contents
is returned. This is a common helper for form-to-image conversion,
and to read hardcopy images from the screen.

fromScreen: aRectangle

read an image from the display screen.
WARNING: this temporarily grabs the display
it may not work from within a buttonMotion
(use #fromScreen:on:grab: with a false grabArg then).

fromScreen: aRectangle on: aDevice

read an image from aDevices display screen.
Since I have no other displays, only the MonoChrome, StaticGrey
and PseudoColor cases have been tested ...
(especially True- and DirectColor may be wrong).
Late note: 24bit rgb now also works.
WARNING: this temporarily grabs the display
it may not work from within a buttonMotion
(use #fromScreen:on:grab: with a false grabArg then).

usage example(s):

     Image fromScreen:((0 @ 0) corner:(100 @ 100)) on:Display
     Image fromScreen:((0 @ 0) corner:(500 @ 500)) on:Display

fromScreen: aRectangle on: aDevice grab: doGrab

read an image from aDevice's display screen.
If the doGrab argument is true, the display
is grabbed (i.e. blocked for others) and a camera cursor is
shown while the readout is done.
Since I have no other displays, only the MonoChrome, StaticGrey
and PseudoColor cases have been tested ...
(especially True- and DirectColor may be wrong).
Late note: 24bit rgb now also works.
WARNING: with doGrab true, this temporarily grabs the display
and it may not work from within a buttonMotion
(use with a false grabArg then).

usage example(s):

     Image fromScreen:((100@100) corner:(200@200)) on:Display grab:false
     Image fromScreen:((100@100) corner:(200@200)) on:Display grab:true

photometricFromScreen: aDevice

read aDevices display photometric and set my colormap for it.
This must be used after an images bits have been read from the screen
or from an offScreen bitmap, for correct pixel interpretation.

virtual anti-aliased

virtualAntiAliasedAlongXvertical: bottomOrTop horizontal: leftOrRight form: tempForm color: aColor xRun: xRun yRun: yRun colorDictionary: colorDictionary blendStart: blendStart
virtualAntiAliasedAlongYhorizontal: leftOrRight vertical: bottomOrTop form: tempForm color: aColor xRun: xRun yRun: yRun colorDictionary: colorDictionary blendStart: blendStart

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)

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

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

    (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

better use package relative file names:

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

various file formats are supported:

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

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

drawing

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

The following examples demonstrate various depth and colorMap variations ... inline image: default: depth=1 & #blackIs0

    (Image
        width:8 height:8
        fromArray:#( 2r11111111
                     2r10000001
                     2r10000001
                     2r10000001
                     2r10000001
                     2r10000001
                     2r10000001
                     2r11111111 )
    ) edit

with #whiteIs0 photometric

    ((Image width:8 height:8
           fromArray:#( 2r11111111
                        2r10000001
                        2r10000001
                        2r10000001
                        2r10000001
                        2r10000001
                        2r10000001
                        2r11111111 ))
        photometric:#whiteIs0
    ) edit

with a colorMap

    ((Image width:8 height:8
           fromArray:#( 2r11111111
                        2r10000001
                        2r10000001
                        2r10000001
                        2r10000001
                        2r10000001
                        2r10000001
                        2r11111111 ))
        colorMap:(Array with:(Color red)
                        with:(Color yellow))
    ) edit

a depth4 greyScale image: (default photometric is #blackIs0)

    (Depth4Image
         width:8
         height:4
         fromArray:#[
                        16r00 16r11 16r22 16r33
                        16r44 16r55 16r66 16r77
                        16r88 16r99 16raa 16rbb
                        16rcc 16rdd 16ree 16rff
                    ]
    ) edit

the same, magnified:

    ((Depth4Image
         width:4
         height:4
         fromArray:#[
                        16r01 16r23
                        16r45 16r67
                        16r89 16rab
                        16rcd 16ref
                    ])
        magnifiedBy:30
    ) edit

the following has the same effect:

    ((Image
         width:4
         height:4
         depth:4
         fromArray:#[
                        16r01 16r23
                        16r45 16r67
                        16r89 16rab
                        16rcd 16ref
                    ])
        magnifiedBy:30
    ) edit

with reverse grey-interpretation:

    ((Depth4Image
         width:4
         height:4
         fromArray:#[
                        16r01 16r23
                        16r45 16r67
                        16r89 16rab
                        16rcd 16ref
                    ])
        photometric:#whiteIs0;
        magnifiedBy:30
    ) edit

with 1-bit-per-pixel rgb interpretation:

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

with 1/2/1 rgb interpretation:

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

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

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

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

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

a 2plane greyscale image:

    ((Depth2Image
         width:4
         height:4
         fromArray:#[
                        4r0123
                        4r1230
                        4r2301
                        4r3012
                    ])
        magnifiedBy:30
    ) edit

with colors:

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

depth4 image with 1/1/1 rgb interpretation:

    ((Depth4Image
         width:4
         height:4
         fromArray:#[
                        16r44 16r44
                        16r22 16r22
                        16r11 16r11
                        16r00 16r00
                    ])
        photometric:#rgb;
        samplesPerPixel:3;
        bitsPerSample:#(1 1 1);
        magnifiedBy:30
    ) edit

depth4 image with 1/2/1 rgb interpretation:

    ((Depth4Image
         width:4
         height:4
         fromArray:#[
                        16rCC 16r44
                        16rAA 16r22
                        16r99 16r11
                        16r88 16r00
                    ])
        photometric:#rgb;
        samplesPerPixel:3;
        bitsPerSample:#(1 2 1);
        magnifiedBy:30
    ) edit

depth8 image with 3/3/2 rgb interpretation:

    ((Depth8Image
         width:16
         height:16
         fromArray:(ByteArray withAll:(0 to:16rFF)))
        photometric:#rgb;
        samplesPerPixel:3;
        bitsPerSample:#(3 3 2);
        magnifiedBy:10
    ) edit

depth8 image with 2/2/2 rgb interpretation:

    ((Depth8Image
         width:8
         height:8
         fromArray:(ByteArray withAll:(0 to:16r3F)))
        photometric:#rgb;
        samplesPerPixel:3;
        bitsPerSample:#(2 2 2);
        magnifiedBy:10
    ) edit

    ((Depth8Image
         width:4
         height:4
         fromArray:#[
                16r30 16r0C  16r03 16r3F
                16r20 16r08  16r02 16r2A
                16r10 16r04  16r01 16r15
                16r00 16r00  16r00 16r00
                    ])
        photometric:#rgb;
        samplesPerPixel:3;
        bitsPerSample:#(2 2 2);
        magnifiedBy:30
    ) edit

trueColor image: remember: bytes are MSB

    ((Depth16Image
         width:4
         height:5
         fromArray:#[
                2r01111100 2r00000000  2r00000011 2r11100000  2r00000000 2r00011111  2r01111111 2r11111111
                2r00111100 2r00000000  2r00000001 2r11100000  2r00000000 2r00001111  2r00111101 2r11101111
                2r00011100 2r00000000  2r00000000 2r11100000  2r00000000 2r00000111  2r00011100 2r11100111
                2r00001100 2r00000000  2r00000000 2r01100000  2r00000000 2r00000001  2r00001100 2r01100011
                2r00000100 2r00000000  2r00000000 2r00100000  2r00000000 2r00000001  2r00000100 2r00100001
                    ])
        photometric:#rgb;
        samplesPerPixel:3;
        bitsPerSample:#(5 5 5);
        magnifiedBy:30
    ) edit

    ((Depth24Image
         width:4
         height:4
         fromArray:#[
                16rFF 16r00 16r00  16rFF 16r00 16r00  16rFF 16r00 16r00  16rFF 16r00 16r00
                16r00 16rFF 16r00  16r00 16rFF 16r00  16r00 16rFF 16r00  16r00 16rFF 16r00
                16r00 16r00 16rFF  16r00 16r00 16rFF  16r00 16r00 16rFF  16r00 16r00 16rFF
                16rFF 16rFF 16rFF  16rFF 16rFF 16rFF  16rFF 16rFF 16rFF  16rFF 16rFF 16rFF
                    ])
        photometric:#rgb;
        samplesPerPixel:3;
        bitsPerSample:#(8 8 8);
        magnifiedBy:30
    ) edit

32bit trueColor image:

    ((Depth32Image
         width:4
         height:4
         fromArray:#[
                16rFF 16r00 16r00 16r00  16rFF 16r00 16r00 16r00  16rFF 16r00 16r00 16r00  16rFF 16r00 16r00 16r00
                16r00 16rFF 16r00 16r00  16r00 16rFF 16r00 16r00  16r00 16rFF 16r00 16r00  16r00 16rFF 16r00 16r00
                16r00 16r00 16rFF 16r00  16r00 16r00 16rFF 16r00  16r00 16r00 16rFF 16r00  16r00 16r00 16rFF 16r00
                16rFF 16rFF 16rFF 16r00  16rFF 16rFF 16rFF 16r00  16rFF 16rFF 16rFF 16r00  16rFF 16rFF 16rFF 16r00
                    ])
        photometric:#rgb;
        samplesPerPixel:4;
        bitsPerSample:#(8 8 8 8);
        magnifiedBy:30
    ) edit

storing - only a subset of formats (TIFF, XBM, XPM) currently support storing:

    |img|

    img := Image fromFile:'bitmaps/winBitmaps/okSmily_up.bmp' inPackage:'stx:goodies'.
    img saveOn:'myImage.tiff'.
    (Image fromFile:'myImage.tiff') inspect.
    img saveOn:'myImage.gif'.
    (Image fromFile:'myImage.gif') inspect.

magnifying (any factor):

    ((Image fromFile:'bitmaps/gifImages/claus.gif' inPackage:'stx:goodies')
        magnifiedTo:(48@48))
            inspect

    ((Image fromFile:'bitmaps/gifImages/claus.gif' inPackage:'stx:goodies')
        magnifiedBy:0.7)
            inspect

rotating (any angle in degrees clockwise):

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

    (((Image fromFile:'bitmaps/gifImages/claus.gif' inPackage:'stx:goodies')
        magnifiedBy:0.3@0.7) rotated:270)
            inspect

    (((Image fromFile:'bitmaps/gifImages/claus.gif' inPackage:'stx:goodies')
        ) rotated:30)
            inspect

negative:

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

depth32 image with 8+8+8+8 argb interpretation:

    ((Depth32Image
         width:4 height:4
         fromArray:#[
            255 255 0 0       255 255 0 0       255 255 0 0       255 255 0 0
            255 0 255 0       255 0 255 0       255 0 255 0       255 0 255 0
            255 0 0 255       255 0 0 255       255 0 0 255       255 0 0 255
            255 255 255 255   255 255 255 255   255 255 255 255   255 255 255 255 ])
        photometric:#argb;
        samplesPerPixel:4;
        bitsPerSample:#(8 8 8 8);
        magnifiedBy:10
    ) edit

depth32 image with 8+8+8+8 rgba interpretation:

    ((Depth32Image
         width:4 height:4
         fromArray:#[
            255 0 0 255       255 0 0 255       255 0 0 255       255 0 0 255
            0 255 0 255       0 255 0 255       0 255 0 255       0 255 0 255
            0 0 255 255       0 0 255 255       0 0 255 255       0 0 255 255
            255 255 255 255   255 255 255 255   255 255 255 255   255 255 255 255 ])
        photometric:#rgba;
        samplesPerPixel:4;
        bitsPerSample:#(8 8 8 8);
        magnifiedBy:10
    ) edit

conversion:

    |d32Image d24Image|

    d32Image := (Depth32Image
         width:4 height:4
         fromArray:#[
            255 0 0 255       255 0 0 255       255 0 0 255       255 0 0 255
            0 255 0 255       0 255 0 255       0 255 0 255       0 255 0 255
            0 0 255 255       0 0 255 255       0 0 255 255       0 0 255 255
            255 255 255 255   255 255 255 255   255 255 255 255   255 255 255 255 ])
        photometric:#rgba;
        samplesPerPixel:4;
        bitsPerSample:#(8 8 8 8);
        magnifiedBy:10.
    d32Image inspect.
    d24Image := Depth24Image fromImage:d32Image.
    d24Image inspect.

ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Wed, 24 Apr 2024 09:04:01 GMT