OME::Image::Server::Pixels - interface for reading files
The OME::Image::Pixels interface provides a generalized way of reading and writing to pixels files. This is provided as a generic class to ease the transition from a local image repository to the image server. There are currently two implementations of this interface -- OME::Image::LocalPixels and OME::Image::Server::Pixels.
A pixels file has an explicitly defined life cycle: It can only be written to immediately after creation. Once the writing has finished, and the pixels marked as complete, they cannot be written to anymore. Further, they cannot be read from until the writing phase is finished.
my $pixels = OME::Image::Server::Pixels->
new($xx,$yy,$zz,$cc,$tt,$bytesPerPixel,$isSigned,$isFloat);
my $pixels = OME::Image::Server::Pixels->open($pixelsID);
my $pixelsID = $pixels->getPixelsID();
my ($x,$y,$z,$c,$t,$bytesPerPixel) = $pixels->getDimensions();
Returns the dimensions (in pixels) of the pixels files.
my $sha1 = $pixels->getSHA1();
Returns a SHA-1 digest of the entire pixels file. This method should throw an error if the pixels file is not readable.
my $readable = $pixels->isReadable();
Returns whether a pixels file is readable, i.e., that the
finishPixels method has been called on this pixels file at some
point in the past.
my $writeable = $pixels->isWriteable();
Returns whether a pixels file is writeable, i.e., that the
finishPixels method has never been called on this pixels file.
my $buf = $pixels->getPixels($bigEndian);
Returns the entire pixel array from this file. The $bigEndian parameter specifies which endian-ness you want the pixels to be in. If not specified, it defaults to network order (big-endian).
my $hash = $pixels->getStackStatistics();
see also OME::Image::Server->getStackStatistics =cut
sub getStackStatistics { my ($self) = @_; return OME::Image::Server-> getStackStatistics($self->[PIXELS_ID]); }
my $buf = $pixels->getStack($c,$t,$bigEndian);
Returns one stack of pixels from this file. The $bigEndian parameter specifies which endian-ness you want the pixels to be in. If not specified, it defaults to network order (big-endian).
my $buf = $pixels->getPlane($z,$c,$t,$bigEndian);
Returns one plane of pixels from this file. The $bigEndian parameter specifies which endian-ness you want the pixels to be in. If not specified, it defaults to network order (big-endian).
my $roi = $pixels->getROI($x0,$y0,$z0,$c0,$t0,
$x1,$y1,$z1,$c1,$t1,
$bigEndian);
Returns an arbitrary hyper-rectangular region of pixels from this file. The $bigEndian parameter specifies which endian-ness you want the pixels to be in. If not specified, it defaults to network order (big-endian).
$pixels->setPixels($buf,$bigEndian);
Sets the entire pixel array for this file. The $bigEndian parameter specifies which endian-ness the given pixels are in. If not specified, it defaults to network order (big-endian). $buf is a binary scalar. Instead of $buf, you can pass the filename if you use setPixelsFile.
$pixels->setStack($buf,$c,$t,$bigEndian);
Sets a single stack of pixels for this file. The $bigEndian parameter specifies which endian-ness the given pixels are in. If not specified, it defaults to network order (big-endian).
$pixels->setPlane($buf,$z,$c,$t,$bigEndian);
Sets a single plane of pixels for this file. The $bigEndian parameter specifies which endian-ness the given pixels are in. If not specified, it defaults to network order (big-endian).
$pixels->setROI($buf,
$x0,$y0,$z0,$c0,$t0,
$x1,$y1,$z1,$c1,$t1,
$bigEndian);
Sets an arbitrary hyper-rectangular region of pixels for this file. The $bigEndian parameter specifies which endian-ness the given pixels are in. If not specified, it defaults to network order (big-endian).
# set the Thumbnail image from a display options attribute.
$pixels->setThumb( $displayOptions );
# set the Thumbnail image from data
$pixels->setThumb(
theT => $theT,
theZ => $theZ,
Red => [$channelIndex, $blackLevel, $whiteLevel, $gamma],
Green => [$channelIndex, $blackLevel, $whiteLevel, $gamma],
Blue => [$channelIndex, $blackLevel, $whiteLevel, $gamma],
Gray => [$channelIndex, $blackLevel, $whiteLevel, $gamma],
LevelBasis => $levelBasis
);
Sets an thumbnail image for this Pixels. see also OME::Image::Server->setThumb
$pixels->convert($fileID,$offset,$bigEndian);
Copies pixels from an original file into a new pixels file. The $file parameter should be an instance of the OME::File interface.
The Pixels in this file are in XYZCT order, which matches the order in Pixels files. Otherwise, you would call ConvertRows, ConvertPlane, ConvertTIFF or ConvertStack. The optional Offset parameter is used to skip headers. It is the number of bytes from the begining of the file to begin reading.
The $bigEndian parameter should specify the endian-ness of the pixels to be copied out of the $file object. If it isn't specified, it defaults to network order (big-endian).
$pixels->convertStack($file,$offset,$c,$t,$bigEndian);
Fills in a stack in this pixels file from another file. The $file parameter should be an instance of the OME::File interface. This is equivalent to the following code snippet, assuming that $size is the size, in bytes, of an XYZ stack in this pixels file:
my $buf = $file->readData($offset,$size);
$pixels->setStack($buf,$c,$t,$bigEndian);
The $bigEndian parameter should specify the endian-ness of the pixels to be copied out of the $file object. If it isn't specified, it defaults to network order (big-endian).
$pixels->convertPlane($file,$offset,$z,$c,$t,$bigEndian, $flippedHorizontal);
Fills in a plane in this pixels file from another file. The $file parameter should be an instance of the OME::File interface. This is equivalent to the following code snippet, assuming that $size is the size, in bytes, of an XY plane in this pixels file:
my $buf = $file->readData($offset,$size);
$pixels->setPlane($buf,$z,$c,$t,$bigEndian);
This class provides a default implementation which is, in fact, this code snippet. However, cooperative implementations of OME::File and OME::Image::Pixels can possibly execute the convertPlane method much faster. (For instance, by reducing the necessary amount of data transfer.)
The $bigEndian parameter should specify the endian-ness of the pixels to be copied out of the $file object. If it isn't specified, it defaults to network order (big-endian).
$pixels->convertPlaneFromTIFF($tiffFile,$z,$c,$t,$IFD);
Fills in a plane in the pixels file from another file, which is assumed to be in the TIFF format. The TIFF is assumed to contain exactly one plane of pixels per IFD. The default IFD is 0.
$pixels->convertRows($file,$offset,$y,$numRows,$z,$c,$t,$bigEndian);
Fills in a row of pixels in this pixels file from another file. The $file parameter should be an instance of the OME::File interface. This is equivalent to the following code snippet, assuming that $size is the size, in bytes, of a row of pixels in this file, and that $sizeX is the size of the X dimension of the pixels:
my $buf = $file->readData($offset,$size * $numRows);
$pixels->setROI($buf,
0,$y,$z,$c,$t,
$sizeX,$y+$numRows,$z+1,$c+1,$t+1,
$bigEndian);
This class provides a default implementation which is, in fact, this code snippet. However, cooperative implementations of OME::File and OME::Image::Pixels can possibly execute the convertRows method much faster. (For instance, by reducing the necessary amount of data transfer.)
The $bigEndian parameter should specify the endian-ness of the pixels to be copied out of the $file object. If it isn't specified, it defaults to network order (big-endian).
$pixels->finishPixels();
Marks the end of the writeable phase of this pixels file's life cycle. After this method has been called, none of the set* or convert* methods can be called.
$pixels->deletePixels();
Deletes the Pixels from the image server - this cannot be undone.
my $filename = $self->getTemporaryLocalPixels($big_endian);
This method should be used for legacy code which must read the pixels from a local file. Returns the filename of a local file, copying the pixels from wherever they might be. This local file can be opened for reading. When the file is no longer needed, it should be closed, and the finishLocalPixels method should be called.
The $big_endian parameter can be specified to the get the pixels file in a certian endianness. If it is omitted, then the pixels will be returned in the endianness of the local machine.
my $filename = $self->getTemporaryLocalStack($c,$t,$big_endian);
This method should be used for legacy code which must read the pixels from a local file. Returns the filename of a local file, copying the specified stack from wherever they might be. This local file can be opened for reading. When the file is no longer needed, it should be closed, and the finishLocalPixels method should be called.
The $big_endian parameter can be specified to the get the pixels file in a certian endianness. If it is omitted, then the pixels will be returned in the endianness of the local machine.
my $filename = $self->getTemporaryLocalPlane($z,$c,$t,$big_endian);
This method should be used for legacy code which must read the pixels from a local file. Returns the filename of a local file, copying the specified plane from wherever they might be. This local file can be opened for reading. When the file is no longer needed, it should be closed, and the finishLocalPixels method should be called.
The $big_endian parameter can be specified to the get the pixels file in a certian endianness. If it is omitted, then the pixels will be returned in the endianness of the local machine.
my $filename = $self->
getTemporaryLocalROI($x0,$y0,$z0,$c0,$t0,
$x1,$y1,$z1,$c1,$t1,
$big_endian);
This method should be used for legacy code which must read the pixels from a local file. Returns the filename of a local file, copying the specified ROI from wherever they might be. This local file can be opened for reading. When the file is no longer needed, it should be closed, and the finishLocalPixels method should be called.
The $big_endian parameter can be specified to the get the pixels file in a certian endianness. If it is omitted, then the pixels will be returned in the endianness of the local machine.
Douglas Creager <dcreager@alum.mit.edu>, Open Microscopy Environment, MIT