OmeroBlitz API
Home Previous Up Next Index

omero::api::RawPixelsStore

Overview

[ "ami", "amd" ] interface RawPixelsStore extends PyramidService

Binary data provider. Initialized with the ID of a model::Pixels instance, this service can provide various slices, stacks, regions of the 5-dimensional (X-Y planes with multiple Z-sections and Channels over Time). The byte array returned by the getter methods and passed to the setter methods can and will be interpreted according to results of {@code getByteWidth}, {@code isFloat}, and {@code isSigned}.

Read-only caveat: Mutating methods (set*) are only available during the first access. Once the Pixels data has been successfully saved (via the save or close methods on this interface), then the data should be treated read-only. If Pixels data writing fails and the service is inadvertently closed, delete the Pixels object, and create a new one. Any partially written data will be removed.

Operation Index

setPixelsId
Initializes the stateful service for a given Pixels set.
getPixelsId
Returns the current Pixels set identifier.
getPixelsPath
Returns the current Pixels path.
prepare
Prepares the stateful service with a cache of loaded Pixels objects.
getPlaneSize
Retrieves the in memory size of a 2D image plane in this pixel store.
getRowSize
Retrieves the in memory size of a row or scanline of pixels in this pixel store.
getStackSize
Retrieves the in memory size of the entire number of optical sections for a single wavelength or channel at a particular timepoint in this pixel store.
getTimepointSize
Retrieves the in memory size of the entire number of optical sections for all wavelengths or channels at a particular timepoint in this pixel store.
getTotalSize
Retrieves the in memory size of the entire pixel store.
getRowOffset
Retrieves the offset for a particular row or scanline in this pixel store.
getPlaneOffset
Retrieves the offset for a particular 2D image plane in this pixel store.
getStackOffset
Retrieves the offset for the entire number of optical sections for a single wavelength or channel at a particular timepoint in this pixel store.
getTimepointOffset
Retrieves the in memory size of the entire number of optical sections for all wavelengths or channels at a particular timepoint in this pixel store.
getTile
Retrieves a tile from this pixel buffer.
getHypercube
Retrieves a n-dimensional block from this pixel store.
getRegion
Retrieves a region from this pixel store.
getRow
Retrieves a particular row or scanline from this pixel store.
getCol
Retrieves a particular column from this pixel store.
getPlane
Retrieves a particular 2D image plane from this pixel store.
getPlaneRegion
Retrieves a region from a given plane from this pixel store.
getStack
Retrieves the the entire number of optical sections for a single wavelength or channel at a particular timepoint in this pixel store.
getTimepoint
Retrieves the entire number of optical sections for all wavelengths or channels at a particular timepoint in this pixel store.
setTile
Sets a tile in this pixel buffer.
setRegion
Sets a region in this pixel buffer.
setRow
Sets a particular row or scanline in this pixel store.
setPlane
Sets a particular 2D image plane in this pixel store.
setStack
Sets the entire number of optical sections for a single wavelength or channel at a particular timepoint in this pixel store.
setTimepoint
Sets the entire number of optical sections for all wavelengths or channels at a particular timepoint in this pixel store.
getHistogram
Retrieves the histogram data for the specified plane and channels.
findMinMax
Find the minimum and maximum pixel values for the specified channels by iterating over a full plane.
getByteWidth
Returns the byte width for the pixel store.
isSigned
Returns whether or not the pixel store has signed pixels.
isFloat
Returns whether or not the pixel buffer has floating point pixels.
calculateMessageDigest
Calculates a SHA-1 message digest for the entire pixel store.
save
Save the current state of the pixels, updating the SHA1.

Operations

void setPixelsId(long pixelsId, bool bypassOriginalFile) throws ServerError

Initializes the stateful service for a given Pixels set.

Parameters

pixelsId
Pixels set identifier.
bypassOriginalFile
Whether or not to bypass checking for an original file to back the pixel buffer used by this service. If requests are predominantly write-only or involve the population of a brand new pixel buffer using true here is a safe optimization otherwise false is expected. See Read-only caveat under RawPixelsStore

long getPixelsId() throws ServerError

Returns the current Pixels set identifier.

Return Value

See above.

string getPixelsPath() throws ServerError

Returns the current Pixels path.

Return Value

See above.

void prepare(sys::LongList pixelsIds) throws ServerError

Prepares the stateful service with a cache of loaded Pixels objects. This method is designed to combat query overhead, where many sets of Pixels are to be read from or written to, by loading all the Pixels sets at once. Multiple calls will result in the existing cache being overwritten.

Parameters

pixelsIds
Pixels IDs to cache.

long getPlaneSize() throws ServerError

Retrieves the in memory size of a 2D image plane in this pixel store.

Return Value

2D image plane size in bytes sizeX*sizeY*byteWidth.

int getRowSize() throws ServerError

Retrieves the in memory size of a row or scanline of pixels in this pixel store.

Return Value

row or scanline size in bytes sizeX*byteWidth

long getStackSize() throws ServerError

Retrieves the in memory size of the entire number of optical sections for a single wavelength or channel at a particular timepoint in this pixel store.

Return Value

stack size in bytes sizeX*sizeY*byteWidth.

long getTimepointSize() throws ServerError

Retrieves the in memory size of the entire number of optical sections for all wavelengths or channels at a particular timepoint in this pixel store.

Return Value

timepoint size in bytes sizeX*sizeY*sizeZ*sizeC*byteWidth.

long getTotalSize() throws ServerError

Retrieves the in memory size of the entire pixel store.

Return Value

total size of the pixel size in bytes sizeX*sizeY*sizeZ*sizeC*sizeT*byteWidth.

long getRowOffset(int y, int z, int c, int t) throws ServerError

Retrieves the offset for a particular row or scanline in this pixel store.

Parameters

y
offset across the Y-axis of the pixel buffer.
z
offset across the Z-axis of the pixel buffer.
c
offset across the C-axis of the pixel buffer.
t
offset across the T-axis of the pixel buffer.

Return Value

offset of the row or scanline.

long getPlaneOffset(int z, int c, int t) throws ServerError

Retrieves the offset for a particular 2D image plane in this pixel store.

Parameters

z
offset across the Z-axis of the pixel buffer.
c
offset across the C-axis of the pixel buffer.
t
offset across the T-axis of the pixel buffer.

Return Value

offset of the 2D image plane.

long getStackOffset(int c, int t) throws ServerError

Retrieves the offset for the entire number of optical sections for a single wavelength or channel at a particular timepoint in this pixel store.

Parameters

c
offset across the C-axis of the pixel buffer.
t
offset across the T-axis of the pixel buffer.

Return Value

offset of the stack.

long getTimepointOffset(int t) throws ServerError

Retrieves the in memory size of the entire number of optical sections for all wavelengths or channels at a particular timepoint in this pixel store.

Parameters

t
offset across the T-axis of the pixel buffer.

Return Value

offset of the timepoint.

::Ice::ByteSeq getTile(int z, int c, int t, int x, int y, int w, int h) throws ServerError

Retrieves a tile from this pixel buffer.

Parameters

z
offset across the Z-axis of the pixel buffer.
c
offset across the C-axis of the pixel buffer.
t
offset across the T-axis of the pixel buffer.
x
Top left corner of the tile, X offset.
y
Top left corner of the tile, Y offset.
w
Width of the tile.
h
Height of the tile.

Return Value

buffer containing the data.

::Ice::ByteSeq getHypercube(sys::IntList offset, sys::IntList size, sys::IntList step) throws ServerError

Retrieves a n-dimensional block from this pixel store.

Parameters

offset
offset for each dimension within pixel store.
size
of each dimension (dependent on dimension).
step
needed of each dimension (dependent on dimension).

Return Value

buffer containing the data.

::Ice::ByteSeq getRegion(int size, long offset) throws ServerError

Retrieves a region from this pixel store.

Parameters

size
byte width of the region to retrieve.
offset
offset within the pixel store.

Return Value

buffer containing the data.

::Ice::ByteSeq getRow(int y, int z, int c, int t) throws ServerError

Retrieves a particular row or scanline from this pixel store.

Parameters

y
offset across the Y-axis of the pixel store.
z
offset across the Z-axis of the pixel store.
c
offset across the C-axis of the pixel store.
t
offset across the T-axis of the pixel store.

Return Value

buffer containing the data which comprises this row or scanline.

::Ice::ByteSeq getCol(int x, int z, int c, int t) throws ServerError

Retrieves a particular column from this pixel store.

Parameters

x
offset across the X-axis of the pixel store.
z
offset across the Z-axis of the pixel store.
c
offset across the C-axis of the pixel store.
t
offset across the T-axis of the pixel store.

Return Value

buffer containing the data which comprises this column.

::Ice::ByteSeq getPlane(int z, int c, int t) throws ServerError

Retrieves a particular 2D image plane from this pixel store.

Parameters

z
offset across the Z-axis of the pixel store.
c
offset across the C-axis of the pixel store.
t
offset across the T-axis of the pixel store.

Return Value

buffer containing the data which comprises this 2D image plane.

::Ice::ByteSeq getPlaneRegion(int z, int c, int t, int size, int offset) throws ServerError

Retrieves a region from a given plane from this pixel store.

Parameters

z
offset across the Z-axis of the pixel store.
c
offset across the C-axis of the pixel store.
t
offset across the T-axis of the pixel store.
size
the number of pixels to retrieve.
offset
the offset at which to retrieve size pixels.

Return Value

buffer containing the data which comprises the region of the given 2D image plane. It is guaranteed that this buffer will have been byte swapped.

::Ice::ByteSeq getStack(int c, int t) throws ServerError

Retrieves the the entire number of optical sections for a single wavelength or channel at a particular timepoint in this pixel store.

Parameters

c
offset across the C-axis of the pixel store.
t
offset across the T-axis of the pixel store.

Return Value

buffer containing the data which comprises this stack.

::Ice::ByteSeq getTimepoint(int t) throws ServerError

Retrieves the entire number of optical sections for all wavelengths or channels at a particular timepoint in this pixel store.

Parameters

t
offset across the T-axis of the pixel store.

Return Value

buffer containing the data which comprises this stack.

void setTile(::Ice::ByteSeq buf, int z, int c, int t, int x, int y, int w, int h) throws ServerError

Sets a tile in this pixel buffer.

Parameters

buf
A byte array of the data.
z
offset across the Z-axis of the pixel buffer.
c
offset across the C-axis of the pixel buffer.
t
offset across the T-axis of the pixel buffer.
x
Top left corner of the tile, X offset.
y
Top left corner of the tile, Y offset.
w
Width of the tile.
h
Height of the tile.

Exceptions

IOException
if there is a problem writing to the pixel buffer.
BufferOverflowException
if an attempt is made to write off the end of the file. See Read-only caveat under RawPixelsStore

void setRegion(int size, long offset, ::Ice::ByteSeq buf) throws ServerError

Sets a region in this pixel buffer.

Parameters

size
byte width of the region to set.
offset
offset within the pixel buffer.
buf
a byte array of the data. See Read-only caveat under RawPixelsStore

void setRow(::Ice::ByteSeq buf, int y, int z, int c, int t) throws ServerError

Sets a particular row or scanline in this pixel store.

Parameters

buf
a byte array of the data comprising this row or scanline.
y
offset across the Y-axis of the pixel store.
z
offset across the Z-axis of the pixel store.
c
offset across the C-axis of the pixel store.
t
offset across the T-axis of the pixel store. See Read-only caveat under RawPixelsStore

void setPlane(::Ice::ByteSeq buf, int z, int c, int t) throws ServerError

Sets a particular 2D image plane in this pixel store.

Parameters

buf
a byte array of the data comprising this 2D image plane.
z
offset across the Z-axis of the pixel store.
c
offset across the C-axis of the pixel store.
t
offset across the T-axis of the pixel store. See Read-only caveat under RawPixelsStore

void setStack(::Ice::ByteSeq buf, int z, int c, int t) throws ServerError

Sets the entire number of optical sections for a single wavelength or channel at a particular timepoint in this pixel store.

Parameters

buf
a byte array of the data comprising this stack.
c
offset across the C-axis of the pixel store.
t
offset across the T-axis of the pixel store. See Read-only caveat under RawPixelsStore

void setTimepoint(::Ice::ByteSeq buf, int t) throws ServerError

Sets the entire number of optical sections for all wavelengths or channels at a particular timepoint in this pixel store.

Parameters

buf
a byte array of the data comprising this timepoint.
t
offset across the T-axis of the pixel buffer. See Read-only caveat under RawPixelsStore

IntegerIntegerArrayMap getHistogram(IntegerArray channels, int binCount, bool globalRange, romio::PlaneDef plane) throws ServerError

Retrieves the histogram data for the specified plane and channels. This method can currently only handle non-pyramid images.

Parameters

channels
the channels to generate the histogram data for
binCount
the number of the histogram bins (optional, default: 256)
plane
the plane (optional, default: whole region of first z/t plane)
globalRange
use the global minimum/maximum to determine the histogram range, otherwise use plane minimum/maximum value

Return Value

See above.

IntegerDoubleArrayMap findMinMax(IntegerArray channels) throws ServerError

Find the minimum and maximum pixel values for the specified channels by iterating over a full plane. In case of multi-z/t images only the 'middle' plane with index maxZ/2, respectively maxT/2 is taken into account. Note: This method can currently only handle non-pyramid images, otherwise an empty map will be returned.

Parameters

channels
the channels

Return Value

See above.

int getByteWidth() throws ServerError

Returns the byte width for the pixel store.

Return Value

See above.

bool isSigned() throws ServerError

Returns whether or not the pixel store has signed pixels.

Return Value

See above.

bool isFloat() throws ServerError

Returns whether or not the pixel buffer has floating point pixels.

Return Value

See above.

::Ice::ByteSeq calculateMessageDigest() throws ServerError

Calculates a SHA-1 message digest for the entire pixel store.

Return Value

byte array containing the message digest.

model::Pixels save() throws ServerError

Save the current state of the pixels, updating the SHA1. This should only be called AFTER all data is successfully set. Future invocations of set methods may be disallowed. This read-only status will allow background processing (generation of thumbnails, compression, etc.) to begin. More information under RawPixelsStore. A null instance will be returned if no save was performed.


Home Previous Up Next Index