Smalltalk/X Webserver

Documentation of class 'ImageReader':

Class: ImageReader

Inheritance
Description
Class protocol
Instance protocol
Private classes

Inheritance:

   Object
   |
   +--ImageReader
      |
      +--GIFReader
      |
      +--HEICReader
      |
      +--JPEGReader
      |
      +--MacOSXIconReader
      |
      +--PBMReader
      |
      +--PNGReader
      |
      +--TIFFReader
      |
      +--WindowsIconReader
      |
      +--XBMReader
      |
      +--XPMReader

Package:: stx:libview

Category:: Graphics-Images-Readers

Version:: rev: 1.165 date: 2023/08/07 11:14:51; user: cg; file: ImageReader.st directory: libview; module: stx stc-classLibrary: libview

Description:

Abstract class to provide common functions for image-readers/writers.
(i.e. TIFFReader, GIFReader etc.).

In contrast to what the name suggests, ImageReaders are supposed to support
both reading and writing of images
(i.e. the name is somewhat outdated, but kept for historic and backward
compatibility reasons).
They provide functionality similar to Squeak's ImageReaderWriter classes.

ImageReaders are created temporary to read an image from a stream.
Normally, they are not directly used - instead, the image class is
asked to read some file, and return an instance for it:
    Image fromFile:<someFileName>
The Image class will guess the image's format and forward the task to
some concrete ImageReaderClass.
If that class thinks, that the file's format is incorrect,
other readers are tried until some reader class finds the file's format acceptable.

Image readers read the stream and collect all relevant information internally.
Once done with reading, the actual image object is created and
data filled in from the imageReaders collected info.

See the implementation of #fromStream: in concrete subclasses.
The public interfaces are:
     <ConcreteReaderClass> fromFile:aFilename
or:
     <ConcreteReaderClass> fromStream:aStream

If you add a new reader, don't forget to add the method #isValidImageFile:
which should return true, if this reader supports reading a given file.

If your new reader class supports writing files, don't forget to add
#canRepresent:anImage and return true from this method.

writing:
    tell the image, to save itself, via <image> saveOn:fileName
    or <image> saveOn:fileName using:<readerClass>

Subclasses should register themself (in their #initialize) method
towards the MIMETypes registry; i.e.
    MIMETypes defineImageType:<mimeType> suffix:<suffix> reader:self.

copyrightCOPYRIGHT (c) 1991 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

create a reader and let it read a stream (in my format).
Return the reader, NOT the image (however, the reader has already read the image,
so it can be asked with 'reader image').
The stream remains open.

readerClassForFilename: aStringOrFilename

return a reader class, determined by the file's name/suffix

Usage example(s):

     self readerClassForFilename:('http://www.foo.bar/helloworld.png' asURL path)  => PNGReader
     self readerClassForFilename:('http://www.foo.bar/helloworld.gif' asURL path)  => GIFReader
     self readerClassForFilename:('http://www.foo.bar/helloworld.tiff' asURL path) => TIFFReader
     self readerClassForFilename:('http://www.foo.bar/helloworld.jpg' asURL path)  => JPEGReader
     self readerClassForFilename:('http://www.foo.bar/helloworld.heic' asURL path) => HEICReader

readerClassForSuffix: aSuffixString

return a reader class, determined by the file's name/suffix

Usage example(s):

     self readerClassForSuffix:'png'   => PNGReader
     self readerClassForSuffix:'gif'   => GIFReader
     self readerClassForSuffix:'tiff'  => TIFFReader
     self readerClassForSuffix:'jpg'   => JPEGReader
     self readerClassForSuffix:'heic'  => HEICReader

image support

buildMaskFromColor: maskPixelValue for: pixels depth: depth width: width height: height: helper for image formats, where an individual pixel value
has been defined as a mask-pixel (i.e. GIF).
Creates a maskImage, with zeros at positions where the image
has the given pixelValue; all other mask pixels are set to 1.
buildMaskFromColor: maskPixelValue for: pixels width: width height: height: marked as obsolete by cg at 04-05-2023

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

image writing

save: anImage onFile: aFilenameOrFilenameString: save the image in my format on aFileName.
Returns the imageReader instance (bad name; is a writer).
May raise Image cannotRepresentImageSignal,
if the image cannot be represented in that format,
or it is not support
save: anImage onFile: aFileName quality: qualityPercent: save the image in my format on aFileName.
The qualityPercent argument is ignored by all lossless formats.
(however, JPG does care for it.)
Returns the imageReader instance (bad name; is a writer).
May raise Image cannotRepresentImageSignal,
if the image cannot be represented in that format,
or it is not support
save: anImage onStream: aStream: save the image in my format on aStream.
Returns the imageReader instance (bad name; is a writer).
May raise Image cannotRepresentImageSignal,
if the image cannot be represented in that format,
or it is not support
save: anImage onStream: aStream quality: qualityPercent: save the image in my format on a Stream.
The qualityPercent argument is ignored by all lossless formats.
(however, JPG does care for it.)
Returns the imageReader instance (bad name; is a writer).
May raise Image cannotRepresentImageSignal,
if the image cannot be represented in that format,
or it is not support
saveAll: aCollectionOfImages onFile: aFilename: save an image collection in my format on a file.
Not all file formats support multiple images,
so be prepared for an exception to be raised.
saveAll: aCollectionOfImages onStream: aStream: save an image collection in my format on a Stream.
Not all file formats support multiple images,
so be prepared for an exception to be raised.

instance creation

new: (comment from inherited method)
return an instance of myself without indexed variables

private utilities

writingFile: aFilenameOrFilenameString for: something do: aBlock

helper for save image

Usage example(s):

        self writingFile:'/etc' for:nil do:[:arg| self halt].
        self writingFile:'/tmp/ttttt' for:nil do:[:arg| arg nextPutLine:'Hello'].

        self writingFile:'/tmp/ttttt' for:nil do:[:arg| ^ self].
        self assert:'/tmp/ttttt' asFilename exists not

queries

isAbstract: Return if this class is an abstract class.
True is returned here for myself only; false for subclasses.
Abstract subclasses must redefine this again.

signal constants

enforcedImageTypeQuery: the query signal which can be used to override the default type
of image as returned by a reader.
Currently, only PNGReader supports.
Usage:
ImageReader enforcedImageTypeQuery answer:#rgb
do:[
Image fromFile:anRGBAFile
]

testing

canRepresent: anImage

return true, if anImage can be represented in my file format.
must be redefined in concrete subclasses which support saving.

isValidImageFile: aFileName

return true, if aFileName contains an image which I can read.
Not all readers (currently) look into the file; some only look at the filename

Usage example(s):

     XPMReader isValidImageFile:'fooBar'    
     XPMReader isValidImageFile:'../../goodies/bitmaps/xpmBitmaps/device_images/ljet.xpm'      
     XPMReader isValidImageFile:'../../goodies/bitmaps/bitmaps/gifImages/garfield.gif'

isValidImageStream: inStream

return true, if inStream possibly contains an image in a format
which this reader class understands.
The stream is left open and position undefined afterwards.
must be redefined in concrete subclasses
which support reading

Instance protocol:

accessing

bitsPerPixel: return the number of bits per pixel
bitsPerRow: return the number of bits in one scanline of the image
bitsPerSample: return the number of bits per sample
bytesPerRow: return the number of bytes in one scanline of the image
colorMap: return the colormap
compressQuality: qualityPercentIgnoredHere: intentionally ignored here (redefined in JPEGReader)
data: return the raw image data
hasMultipleImages
height: return the height of the image
image: return the image as represented by myself;
If my file contained multiple images, return the first one.
imageFrames: return a collection of all imageFrames as represented by myself.
ImageFrames are wrappers for individual images, which hold
additional information (such as image delay time).
Nil is return for single image formats/files.
images: return a collection of all images as represented by myself.
For compatibility with single-image formats, return a collection
containing my single image here if the file format does not support
multiple images.
Readers for formats with multiple images should leave the images
in the imageSequence instVar as a side effect of reading.
makeImage: return the image as represented by the values found in my
instvars; these have been typically set as a side effect of
the fromStream:-method, which reads images.
mask: return the image mask (or nil)
metaData: non nil, if there was metadata (edif) info present.
numberOfImages: return the number of images as read.
By default (here), I hold a single image;
however, some fileFormats allow for multiple images
orientation: non nil, if there was metadata (edif) info present.
If nil is returned, assume topLeft (i.e. 'normal')
photometric: return the photometric interpretation of the image data.
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
width: return the width of the image

accessing-private

byteOrder: aSymbol: set the byte order - either #lsb or #msb
inStream
inStream: aStream

error reporting

fileFormatError: aMessage: report a format notification - no image could be read.
The notification is ignored if not explicitlay handled.
If handled, it may be proceeded, then a nil is returned
(useful for image sequences as in ICNS)
fileFormatError: aMessage with: argument: report a format notification - no image could be read.
The notification is ignored if not explicitlay handled.
If handled, it may be proceeded, then a nil is returned
(useful for image sequences as in ICNS)

i/o support

readLong: return the next 4-byte long, honoring the byte-order
readShort: return the next 2-byte short, honoring the byte-order
readShortLong: return the next 2-byte short, honoring the byte-order.
There are actually 4 bytes read, but only 2 looked at.
readUnsignedLong: return the next 4-byte long, honoring the byte-order
writeLong: anInteger: write a 4-byte long, honoring the byte-order.
writeShort: anInteger: write a 2-byte short, honoring the byte-order.

image reading

fromStream: aStream: read an image in my format from aStream.
Leave image description in instance variables.
readImage: read an image in my format from my inStream.
Leave image description in instance variables.

** This method must be redefined in concrete classes (subclassResponsibility) **

image reading support

buildMaskFromColor: maskPixelValue: helper for image formats, where an individual pixel value
has been defined as a mask-pixel (eg. GIF).
Creates a maskImage, with zeros at positions where the image
has the given pixelValue; all other mask pixels are set to 1.
processExifData: exifData msb: msbFirst: exif is actually TIFF without an image...

image writing

save: image onFile: aFilenameOrFilenameString: save image in my format on aFile
save: image onFile: aFileName quality: qualityPercentOrNil: save image in my format on aFile
save: image onStream: aStream: save image in my file-format onto aStream
save: image onStream: aStream quality: qualityPercentOrNil: save image in my format on a Stream.
QualityPercent is ignored by lossless formats (jpg uses it)
saveAll: aCollectionOfImages onFile: aFileName: save a collection of images in my format on aFile.
Not all file formats support multiple images,
so be prepared for an exception to be raised.
saveAll: aCollectionOfImages onStream: aStream: save an image collection in my format on a Stream.
Not all file formats support multiple images,
so be prepared for an exception to be raised.

initialization

initialize: (comment from inherited method)
just to ignore initialize to objects which do not need it

progress reporting

dimensionCallBack: aBlock: set the block, which is evaluated during the readProcess, as soon as
the images dimension is known. This is useful for background image reading,
if the size is need to be known (for example: for formatting purposes).
Obsoleted by dimensionHolder.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
dimensionHolder: aValueHolderOrBlock: set the valueHolder or block, which is evaluated during the readProcess,
as soon as the images dimension is known.
Useful for background image reading, if the size is need to be known (for example: for formatting purposes).
progressHolder: aValueHolderOrBlock: set the valueHolder or block, which is evaluated during the readProcess,
and set with progress information (0..100 percent).
Useful for user feedback
reportDimension
reportProgress: fraction: can be used by a GUI application to indicate loading progress (0..1)

Private classes:

    EnforcedImageTypeQuery

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sat, 21 Dec 2024 18:56:52 GMT

Smalltalk/X Webserver

Documentation of class 'ImageReader':

Class: ImageReader

Inheritance:

Description:

copyright

Class protocol:

Instance protocol:

Private classes: