eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ImageReader':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: ImageReader


Inheritance:

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

Package:
stx:libview
Category:
Graphics-Images-Readers
Version:
rev: 1.146 date: 2018/03/27 18:12:11
user: cg
file: ImageReader.st directory: libview
module: stx stc-classLibrary: libview
Author:
Claus Gittinger

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>


Related information:

    Image
    Icon
    Form

Class protocol:

cleanup
o  lowSpaceCleanup
cleanup things we do not need

constants
o  reverseBits
return a table filled with bit reverse information.
To convert from msbit-first to lsbit-first bytes, use
the value as index into the table, retrieving the reverse
value. Since indexing must start at 1, use (value + 1) as
index.

decompression support
o  _decompressCCITT3From: src count: inCount into: dst startingAt: dstIndexIn
toggle if it was a terminating code

o  _decompressCCITT3From: src count: inCount into: dst startingAt: dstIndexIn count: len
toggle if it was a terminating code

o  decodeDelta: step in: data width: width height: height
perform TIFF predictor = 2 delta decoding inplace on data.
Calls primitive c function for speed

o  decompressCCITT3From: srcBytes into: dstBytes startingAt: offset count: count
decompress CCITT Group 3 compressed image data.
count bytes from srcBytes are decompressed into dstBytes.
Calls primitive c function for speed

o  decompressGIFFrom: srcBytes count: count into: dstBytes startingAt: offset codeLen: codeLen
decompress GIF compressed image data.
count bytes from srcBytes are decompressed into dstBytes.
Calls primitive c function for speed

o  decompressLZWFrom: srcBytes count: count into: dstBytes startingAt: offset
decompress LZW (tiff) compressed image data.
count bytes from srcBytes are decompressed into dstBytes.
Calls primitive c function for speed

o  decompressPackBits: nIn from: srcBytes to: dstBytes startingAt: dstOffset
decompress a number of input bytes.
Used by tiff and some mac image formats.
Return the number of decompressed output bytes.

o  decompressPackBitsV2From: srcBytes at: srcStart to: dstBytes at: dstStart count: outCount
decompress until a number of output bytes has been decompressed.
Used by some mac image formats.
Return the number of processed input bytes.
This does NOT treat FF as a noop.

o  decompressRLEFrom: srcBytes at: srcStartIndex into: dstBytes at: dstStartIndex increment: dstIncrement
common helper to expand RLE encoded data

o  decompressTiffPackBitsFrom: srcBytes to: dstBytes at: dstStart count: maxOutCount
decompress all of srcBytes to dstBytes starting at dstStart.
Used by TIFF image formats.
This DOES TREAT FF as a noop.

o  initCCITTTables
0

o  swap: nBytes bytesFromRGBA_to_BGRA_in: data startingAt: startIndex
swap bytes from RGBA into BGRA order.
The argument is a pixel data buffer (byteArray)

o  swap: nBytes bytesFromRGB_to_BGR_in: data
swap bytes from RGB into BGR order.
The argument is a pixel data buffer (byteArray)

o  swap: nBytes bytesFromRGB_to_BGR_in: data startingAt: startIndex
swap bytes from RGB into BGR order.
The argument is a pixel data buffer (byteArray)

o  swap: count pixelsFromRGB_to_BGR_in: data startingAt: startIndex bytesPerPixel: bpp
swap bytes from RGB into BGR order.
The argument is a pixel data buffer (byteArray).
Can be used for both 24bit rgb data (bpp=3) or rgba data (bpp=4)

i/o support
o  streamReadingFile: aFilename
return a stream to read aFilename.
If the filename ends with '.Z' or '.gz', return a stream
to a pipe for the uncompressor. Otherwise, return a stream to read
the file directly.

image reading
o  fromBytes: aByteArray
read an image (in my format) from aByteArray.
Return the image or nil (if unrecognized format or error)

o  fromFile: aFileName
read an image (in my format) from aFileName.
Return the image or nil on error.
usage example(s):
     XBMReader fromFile:'bitmaps/SBrowser.xbm'
     XPMReader fromFile:'bitmaps/xpmBitmaps/misc_icons/BOOK.xpm'
     XBMReader fromFile:'bitmaps/xpmBitmaps/misc_icons/BOOK.xpm'

o  fromStream: aStream
read an image (in my format) from aStream.
Return the image or nil (if unrecognized format or error).
The stream remains open.

o  fromURL: url
read an image (in my format) from url.
Return the image or nil (if unrecognized format or error)
usage example(s):
     self fromURL:'http://www.lutece.paris.fr/tech/images/helloworld.png'

o  imagesFromFile: aFileName
read all images (in my format) from aFileName.
Return a collection of images or nil on error.
Not all reader may support multiple images.

o  imagesFromStream: aStream
read all images (in my format) from aStream.
Return a collection of images or nil (if unrecognized format or error).
The stream remains open.
Not all reader may support multiple images.

o  readFile: aFilename
create a reader and let it read an image (in my format) from aFilename.
Return the reader, NOT the image (however, the reader has already read the image,
so it can be asked with 'reader image').
usage example(s):
     XPMReader readFile:'../../goodies/bitmaps/xpmBitmaps/misc_icons/BOOK.xpm'
     (XPMReader readFile:'../../goodies/bitmaps/xpmBitmaps/misc_icons/BOOK.xpm') image

o  readStream: aStream
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.

o  readerClassForFilename: aStringOrFilename
return a reader class, determined by the file's name
usage example(s):
     self readerClassForFilename:('http://www.foo.bar/helloworld.png' asURL path)
     self readerClassForFilename:('http://www.foo.bar/helloworld.gif' asURL path)

image support
o  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.

o  buildMaskFromColor: maskPixelValue for: pixels 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.

image writing
o  save: anImage onFile: aFileName
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

o  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

o  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

o  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

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

o  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
o  new
(comment from inherited method)
return an instance of myself without indexed variables

queries
o  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
o  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
o  canRepresent: anImage
return true, if anImage can be represented in my file format.
must be redefined in concrete subclasses which support saving.

o  isValidImageFile: aFileName
return true, if aFileName contains an image this
reader understands - must be redefined in concrete subclasses
which support reading.


Instance protocol:

accessing
o  bitsPerPixel
return the number of bits per pixel

o  bitsPerRow
return the number of bits in one scanline of the image

o  bitsPerSample
return the number of bits per sample

o  bytesPerRow
return the number of bytes in one scanline of the image

o  colorMap
return the colormap

o  compressQuality: qualityPercentIgnoredHere
intentionally ignored here (redefined in JPEGReader)

o  data
return the raw image data

o  hasMultipleImages

o  height
return the height of the image

o  image
return the image as represented by myself;
If my file contained multiple images, return the first one.

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

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

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

o  mask
return the image mask (or nil)

o  numberOfImages
return the number of images as read.
By default (here), I hold a single image;
however, some fileFormats allow for multiple images

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

o  samplesPerPixel
return the number of samples per pixel

o  width
return the width of the image

accessing-private
o  byteOrder: aSymbol
set the byte order - either #lsb or #msb

o  inStream

o  inStream: aStream

error reporting
o  fileFormatError: aMessage
report a format error - no image could be read.
The error may be proceeded, then a nil is returned (useful for image sequences as in ICNS)

o  fileFormatError: aMessage with: argument
report a format error - no image could be read.
The error may be proceeded, then a nil is returned (useful for image sequences as in ICNS)

i/o support
o  readLong
return the next 4-byte long, honoring the byte-order

o  readShort
return the next 2-byte short, honoring the byte-order

o  readShortLong
return the next 2-byte short, honoring the byte-order.
There are actually 4 bytes read, but only 2 looked at.

o  readUnsignedLong
return the next 4-byte long, honoring the byte-order

o  writeLong: anInteger
write a 4-byte long, honoring the byte-order.

o  writeShort: anInteger
write a 2-byte short, honoring the byte-order.

image reading
o  fromStream: aStream
read an image in my format from aStream.
Leave image description in instance variables.

o  readImage
read an image in my format from my inStream.
Leave image description in instance variables.

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

image reading support
o  buildMaskFromColor: maskPixelValue
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.

image writing
o  save: image onFile: aFileName
save image in my format on aFile

o  save: image onFile: aFileName quality: qualityPercentOrNil
save image in my format on aFile

o  save: image onStream: aStream
save image in my file-format onto aStream

o  save: image onStream: aStream quality: qualityPercentOrNil
save image in my format on a Stream.
QualityPercent is ignored by lossless formats (jpg uses it)

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

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

o  writingFile: aFileName for: something do: aBlock
helper for save image

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

progress reporting
o  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) **

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

o  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

o  reportDimension

o  reportProgress: fraction
can be used by a GUI application to indicate loading progress (0..1)


Private classes:

    EnforcedImageTypeQuery


ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Sun, 22 Jul 2018 12:49:13 GMT