OmeroBlitz API

omero::api::ThumbnailStore

Overview

[ "ami", "amd" ] interface ThumbnailStore extends StatefulServiceInterface

Provides methods for dealing with thumbnails. Provision is provided to retrieve thumbnails using the on-disk cache (provided by ROMIO) or on the fly.

NOTE: The calling order for the service is as follows:

1. {@code setPixelsId}
2. any of the thumbnail accessor methods or {@code resetDefaults}

Operation Index

setPixelsId

This method manages the state of the service; it must be invoked before using any other methods.

isInProgress

This returns the last available in progress state for a thumbnail.

setRenderingDefId

This method manages the state of the service; it should be invoked directly after {@code setPixelsId}.

getRenderingDefId

Return the id of the model::RenderingDef loaded in this instance.

getThumbnail

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef).

getThumbnailWithoutDefault

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef).

getThumbnailSet

Retrieves a number of thumbnails for pixels sets using given sets of rendering settings (RenderingDef).

getThumbnailByLongestSideSet

Retrieves a number of thumbnails for pixels sets using given sets of rendering settings (RenderingDef).

getThumbnailByLongestSide

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef).

getThumbnailByLongestSideDirect

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef).

getThumbnailDirect

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef).

getThumbnailForSectionDirect

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef) for a particular section.

getThumbnailForSectionByLongestSideDirect

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef) for a particular section.

createThumbnails

Creates thumbnails for a pixels set using a given set of rendering settings (RenderingDef) in the on-disk cache for every sizeX/sizeY combination already cached.

createThumbnail

Creates a thumbnail for a pixels set using a given set of rendering settings (RenderingDef) in the on-disk cache.

createThumbnailsByLongestSideSet

Creates thumbnails for a number of pixels sets using a given set of rendering settings (RenderingDef) in the on-disk cache.

thumbnailExists

Checks if a thumbnail of a particular size exists for a pixels set.

resetDefaults

Resets the rendering definition for the active pixels set to its default settings.

Operations

bool setPixelsId(long pixelsId) throws ServerError

This method manages the state of the service; it must be invoked before using any other methods. As the ThumbnailStore relies on the RenderingEngine, a valid rendering definition must be available for it to work.

Parameters

pixelsId

an model::Pixels id.

Return Value

true if a model::RenderingDef exists for the model::Pixels set, otherwise false

Exceptions

ApiUsageException

if no pixels object exists with the ID pixelsId.

bool isInProgress() throws ServerError

This returns the last available in progress state for a thumbnail. Its return value is only expected to be valid after the call to any of the individual thumbnail retrieval methods.

Return Value

true if the image is in the process of being imported or a pyramid is being generated for it.

void setRenderingDefId(long renderingDefId) throws ServerError

This method manages the state of the service; it should be invoked directly after {@code setPixelsId}. If it is not invoked with a valid rendering definition ID before using the thumbnail accessor methods execution continues as if renderingDefId were set to null.

Parameters

renderingDefId

an model::RenderingDef id. null specifies the user's currently active rendering settings to be used.

Exceptions

ValidationException

if no rendering definition exists with the ID renderingDefId.

long getRenderingDefId() throws ServerError

Return the id of the model::RenderingDef loaded in this instance.

::Ice::ByteSeq getThumbnail(RInt sizeX, RInt sizeY) throws ServerError

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef). If the thumbnail exists in the on-disk cache it will be returned directly, otherwise it will be created as in {@code getThumbnailDirect}, placed in the on-disk cache and returned. If the thumbnail is missing, a clock will be returned to signify that the thumbnail is yet to be generated. {@code setPixelsId} has not yet been called

Parameters

sizeX

the X-axis width of the thumbnail. null specifies the default size of 48.

sizeY

the Y-axis width of the thumbnail. null specifies the default size of 48.

Return Value

a JPEG thumbnail byte buffer.

Exceptions

ApiUsageException

if:

• sizeX is greater than pixels.sizeX
• sizeX is negative
• sizeY is greater than pixels.sizeY
• sizeY is negative
• {

See Also

getThumbnailDirect

::Ice::ByteSeq getThumbnailWithoutDefault(RInt sizeX, RInt sizeY) throws ServerError

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef). If the thumbnail exists in the on-disk cache it will be returned directly, otherwise it will be created as in {@code getThumbnailDirect}, placed in the on-disk cache and returned. If the thumbnail is still to be generated, an empty array will be returned. {@code setPixelsId} has not yet been called

Parameters

sizeX

the X-axis width of the thumbnail. null specifies the default size of 48.

sizeY

the Y-axis width of the thumbnail. null specifies the default size of 48.

Return Value

a JPEG thumbnail byte buffer

Exceptions

ApiUsageException

if:

• sizeX is greater than pixels.sizeX
• sizeX is negative
• sizeY is greater than pixels.sizeY
• sizeY is negative
• {

See Also

getThumbnailDirect

sys::IdByteMap getThumbnailSet(RInt sizeX, RInt sizeY, sys::LongList pixelsIds) throws ServerError

Retrieves a number of thumbnails for pixels sets using given sets of rendering settings (RenderingDef). If the thumbnails exist in the on-disk cache they will be returned directly, otherwise they will be created as in {@code getThumbnailDirect}, placed in the on-disk cache and returned. Unlike the other thumbnail retrieval methods, this method may be called without first calling {@code setPixelsId}.

Parameters

sizeX

the X-axis width of the thumbnail. null specifies the default size of 48.

sizeY

the Y-axis width of the thumbnail. null specifies the default size of 48.

pixelsIds

the Pixels sets to retrieve thumbnails for.

Return Value

a map whose keys are pixels ids and values are JPEG thumbnail byte buffers or null if an exception was thrown while attempting to retrieve the thumbnail for that particular Pixels set.

See Also

getThumbnail

sys::IdByteMap getThumbnailByLongestSideSet(RInt size, sys::LongList pixelsIds) throws ServerError

Retrieves a number of thumbnails for pixels sets using given sets of rendering settings (RenderingDef). If the Thumbnails exist in the on-disk cache they will be returned directly, otherwise they will be created as in {@code getThumbnailByLongestSideDirect}. The longest side of the image will be used to calculate the size for the smaller side in order to keep the aspect ratio of the original image. Unlike the other thumbnail retrieval methods, this method may be called without first calling {@code setPixelsId}.

Parameters

size

the size of the longest side of the thumbnail requested. null specifies the default size of 48.

pixelsIds

the Pixels sets to retrieve thumbnails for.

Return Value

a map whose keys are pixels ids and values are JPEG thumbnail byte buffers or null if an exception was thrown while attempting to retrieve the thumbnail for that particular Pixels set.

See Also

getThumbnailSet

::Ice::ByteSeq getThumbnailByLongestSide(RInt size) throws ServerError

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef). If the thumbnail exists in the on-disk cache it will be returned directly, otherwise it will be created as in {@code getThumbnailDirect}, placed in the on-disk cache and returned. The longest side of the image will be used to calculate the size for the smaller side in order to keep the aspect ratio of the original image. {@code setPixelsId} has not yet been called

Parameters

size

the size of the longest side of the thumbnail requested. null specifies the default size of 48.

Return Value

a JPEG thumbnail byte buffer.

Exceptions

ApiUsageException

if:

• size is greater than pixels.sizeX and pixels.sizeY
• {

See Also

getThumbnail

::Ice::ByteSeq getThumbnailByLongestSideDirect(RInt size) throws ServerError

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef). The Thumbnail will always be created directly, ignoring the on-disk cache. The longest side of the image will be used to calculate the size for the smaller side in order to keep the aspect ratio of the original image. {@code setPixelsId} has not yet been called

Parameters

size

the size of the longest side of the thumbnail requested. null specifies the default size of 48.

Return Value

a JPEG thumbnail byte buffer.

Exceptions

ApiUsageException

if:

• size is greater than pixels.sizeX and pixels.sizeY
• {

See Also

getThumbnailDirect

::Ice::ByteSeq getThumbnailDirect(RInt sizeX, RInt sizeY) throws ServerError

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef). The Thumbnail will always be created directly, ignoring the on-disk cache. {@code setPixelsId} has not yet been called

Parameters

sizeX

the X-axis width of the thumbnail. null specifies the default size of 48.

sizeY

the Y-axis width of the thumbnail. null specifies the default size of 48.

Return Value

a JPEG thumbnail byte buffer.

Exceptions

ApiUsageException

if:

• sizeX is greater than pixels.sizeX
• sizeX is negative
• sizeY is greater than pixels.sizeY
• sizeY is negative
• {

See Also

getThumbnail

::Ice::ByteSeq getThumbnailForSectionDirect(int theZ, int theT, RInt sizeX, RInt sizeY) throws ServerError

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef) for a particular section. The Thumbnail will always be created directly, ignoring the on-disk cache. {@code setPixelsId} has not yet been called

Parameters

theZ

the optical section (offset across the Z-axis) to use.

theT

the timepoint (offset across the T-axis) to use.

sizeX

the X-axis width of the thumbnail. null specifies the default size of 48.

sizeY

the Y-axis width of the thumbnail. null specifies the default size of 48.

Return Value

a JPEG thumbnail byte buffer.

Exceptions

ApiUsageException

if:

• sizeX is greater than pixels.sizeX
• sizeX is negative
• sizeY is greater than pixels.sizeY
• sizeY is negative
• theZ is out of range
• theT is out of range
• {

See Also

getThumbnail

::Ice::ByteSeq getThumbnailForSectionByLongestSideDirect(int theZ, int theT, RInt size) throws ServerError

Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef) for a particular section. The Thumbnail will always be created directly, ignoring the on-disk cache. The longest side of the image will be used to calculate the size for the smaller side in order to keep the aspect ratio of the original image. {@code setPixelsId} has not yet been called

Parameters

theZ

the optical section (offset across the Z-axis) to use.

theT

the timepoint (offset across the T-axis) to use.

size

the size of the longest side of the thumbnail requested. null specifies the default size of 48.

Return Value

a JPEG thumbnail byte buffer.

Exceptions

ApiUsageException

if:

• size is greater than pixels.sizeX and pixels.sizeY
• {

See Also

getThumbnailDirect

void createThumbnails() throws ServerError

Creates thumbnails for a pixels set using a given set of rendering settings (RenderingDef) in the on-disk cache for every sizeX/sizeY combination already cached.

See Also

getThumbnail

getThumbnailDirect

void createThumbnail(RInt sizeX, RInt sizeY) throws ServerError

Creates a thumbnail for a pixels set using a given set of rendering settings (RenderingDef) in the on-disk cache. {@code setPixelsId} has not yet been called

Parameters

sizeX

the X-axis width of the thumbnail. null specifies the default size of 48.

sizeY

the Y-axis width of the thumbnail. null specifies the default size of 48.

Exceptions

ApiUsageException

if:

• sizeX is greater than pixels.sizeX
• sizeX is negative
• sizeY is greater than pixels.sizeY
• sizeY is negative
• {

See Also

getThumbnail

getThumbnailDirect

void createThumbnailsByLongestSideSet(RInt size, sys::LongList pixelsIds) throws ServerError

Creates thumbnails for a number of pixels sets using a given set of rendering settings (RenderingDef) in the on-disk cache. Unlike the other thumbnail creation methods, this method may be called without first calling {@code setPixelsId}. This method will not reset or modify rendering settings in any way. If rendering settings for a pixels set are not present, thumbnail creation for that pixels set will not be performed.

Parameters

size

the size of the longest side of the thumbnail requested. null specifies the default size of 48.

pixelsIds

the Pixels sets to retrieve thumbnails for.

Exceptions

ApiUsageException

if:

• size is greater than pixels.sizeX and pixels.sizeY
• size is negative

See Also

createThumbnail

createThumbnails

bool thumbnailExists(RInt sizeX, RInt sizeY) throws ServerError

Checks if a thumbnail of a particular size exists for a pixels set.

Parameters

sizeX

the X-axis width of the thumbnail. null specifies the default size of 48.

sizeY

the Y-axis width of the thumbnail. null specifies the default size of 48.

Exceptions

ApiUsageException

if:

• sizeX is negative
• sizeY is negative
• setPixelsId has not yet been called

See Also

getThumbnail

getThumbnailDirect

void resetDefaults() throws ServerError

Resets the rendering definition for the active pixels set to its default settings.