Package ome.api

Interface ThumbnailStore

  • All Superinterfaces:
    ServiceInterface, StatefulServiceInterface
    public 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. setPixelsId()
    2. any of the thumbnail accessor methods or resetDefaults()

    Since:
    3.0

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void createThumbnail​(java.lang.Integer sizeX, java.lang.Integer sizeY)
      Creates a thumbnail for a pixels set using a given set of rendering settings (RenderingDef) in the on-disk cache.
      void 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.
      void createThumbnailsByLongestSideSet​(java.lang.Integer size, java.util.Set<java.lang.Long> pixelsIds)
      Creates thumbnails for a number of pixels sets using a given set of rendering settings (RenderingDef) in the on-disk cache.
      long getRenderingDefId()
      Return the id of the RenderingDef loaded in this instance.
      byte[] getThumbnail​(java.lang.Integer sizeX, java.lang.Integer sizeY)
      Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef).
      byte[] getThumbnailByLongestSide​(java.lang.Integer size)
      Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef).
      byte[] getThumbnailByLongestSideDirect​(java.lang.Integer size)
      Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef).
      java.util.Map<java.lang.Long,​byte[]> getThumbnailByLongestSideSet​(java.lang.Integer size, java.util.Set<java.lang.Long> pixelsIds)
      Retrieves a number of thumbnails for pixels sets using given sets of rendering settings (RenderingDef).
      byte[] getThumbnailDirect​(java.lang.Integer sizeX, java.lang.Integer sizeY)
      Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef).
      byte[] getThumbnailForSectionByLongestSideDirect​(int theZ, int theT, java.lang.Integer size)
      Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef) for a particular section.
      byte[] getThumbnailForSectionDirect​(int theZ, int theT, java.lang.Integer sizeX, java.lang.Integer sizeY)
      Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef) for a particular section.
      java.util.Map<java.lang.Long,​byte[]> getThumbnailSet​(java.lang.Integer sizeX, java.lang.Integer sizeY, java.util.Set<java.lang.Long> pixelsIds)
      Retrieves a number of thumbnails for pixels sets using given sets of rendering settings (RenderingDef).
      byte[] getThumbnailWithoutDefault​(java.lang.Integer sizeX, java.lang.Integer sizeY)
      Retrieves a thumbnail for a pixels set using a given set of rendering settings (RenderingDef).
      boolean isInProgress()
      This returns the last available in progress state for a thumbnail.
      void resetDefaults()
      Resets the rendering definition for the active pixels set to its default settings.
      boolean setPixelsId​(long pixelsId)
      This method manages the state of the service; it must be invoked before using any other methods.
      void setRenderingDefId​(long renderingDefId)
      This method manages the state of the service; it should be invoked directly after setPixelsId(long).
      boolean thumbnailExists​(java.lang.Integer sizeX, java.lang.Integer sizeY)
      Checks if a thumbnail of a particular size exists for a pixels set.

    • Method Detail

      • setPixelsId

        boolean setPixelsId​(long pixelsId)
        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 Pixels id.
        Returns:
        true if a RenderingDef exists for the Pixels set, otherwise false
        Throws:
        ApiUsageException - if no pixels object exists with the ID pixelsId.

      • isInProgress

        boolean isInProgress()
        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.
        Returns:
        true if the image is in the process of being imported or a pyramid is being generated for it.

      • setRenderingDefId

        void setRenderingDefId​(long renderingDefId)
        This method manages the state of the service; it should be invoked directly after setPixelsId(long). 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 RenderingDef id. null specifies the user's currently active rendering settings to be used.
        Throws:
        ValidationException - if no rendering definition exists with the ID renderingDefId.

      • getRenderingDefId

        long getRenderingDefId()
        Return the id of the RenderingDef loaded in this instance.

      • getThumbnail

        byte[] getThumbnail​(java.lang.Integer sizeX,
                    java.lang.Integer sizeY)
        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 getThumbnailDirect(Integer, Integer), placed in the on-disk cache and returned.
        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.
        Returns:
        a JPEG thumbnail byte buffer.
        Throws:
        ApiUsageException - if:
        • sizeX is greater than pixels.sizeX
        • sizeX is negative
        • sizeY is greater than pixels.sizeY
        • sizeY is negative
        • setPixelsId(long) has not yet been called
        See Also:
        getThumbnailDirect(Integer, Integer)

      • getThumbnailWithoutDefault

        byte[] getThumbnailWithoutDefault​(java.lang.Integer sizeX,
                                  java.lang.Integer sizeY)
        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 getThumbnailDirect(java.lang.Integer, java.lang.Integer), placed in the on-disk cache and returned. If the thumbnail is still to be generated, an empty array will be returned.
        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.
        Returns:
        a JPEG thumbnail byte buffer
        Throws:
        ApiUsageException - if:
        • sizeX is greater than pixels.sizeX
        • sizeX is negative
        • sizeY is greater than pixels.sizeY
        • sizeY is negative
        • setPixelsId(long) has not yet been called
        See Also:
        getThumbnailDirect(java.lang.Integer, java.lang.Integer)

      • getThumbnailSet

        java.util.Map<java.lang.Long,​byte[]> getThumbnailSet​(java.lang.Integer sizeX,
                                                           java.lang.Integer sizeY,
                                                           java.util.Set<java.lang.Long> pixelsIds)
        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 getThumbnailDirect(Integer, Integer), placed in the on-disk cache and returned. Unlike the other thumbnail retrieval methods, this method may be called without first calling setPixelsId(long).
        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.
        Returns:
        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(Integer, Integer)

      • getThumbnailByLongestSideSet

        java.util.Map<java.lang.Long,​byte[]> getThumbnailByLongestSideSet​(java.lang.Integer size,
                                                                        java.util.Set<java.lang.Long> pixelsIds)
        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 getThumbnailByLongestSideDirect(java.lang.Integer). 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 setPixelsId(long).
        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.
        Returns:
        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(Integer, Integer, Set)

      • getThumbnailByLongestSide

        byte[] getThumbnailByLongestSide​(java.lang.Integer size)
        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 bereturned directly, otherwise it will be created as in getThumbnailDirect(Integer, Integer), 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.
        Parameters:
        size - the size of the longest side of the thumbnail requested. null specifies the default size of 48.
        Returns:
        a JPEG thumbnail byte buffer.
        Throws:
        ApiUsageException - if:
        • size is greater than pixels.sizeX and pixels.sizeY
        • setPixelsId(long) has not yet been called
        See Also:
        getThumbnail(Integer, Integer)

      • getThumbnailDirect

        byte[] getThumbnailDirect​(java.lang.Integer sizeX,
                          java.lang.Integer sizeY)
        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.
        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.
        Returns:
        a JPEG thumbnail byte buffer.
        Throws:
        ApiUsageException - if:
        • sizeX is greater than pixels.sizeX
        • sizeX is negative
        • sizeY is greater than pixels.sizeY
        • sizeY is negative
        • setPixelsId(long) has not yet been called
        See Also:
        getThumbnail(Integer, Integer)

      • getThumbnailForSectionDirect

        byte[] getThumbnailForSectionDirect​(int theZ,
                                    int theT,
                                    java.lang.Integer sizeX,
                                    java.lang.Integer sizeY)
        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.
        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.
        Returns:
        a JPEG thumbnail byte buffer.
        Throws:
        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
        • setPixelsId(long) has not yet been called
        See Also:
        getThumbnail(Integer, Integer)

      • getThumbnailByLongestSideDirect

        byte[] getThumbnailByLongestSideDirect​(java.lang.Integer size)
        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.
        Parameters:
        size - the size of the longest side of the thumbnail requested. null specifies the default size of 48.
        Returns:
        a JPEG thumbnail byte buffer.
        Throws:
        ApiUsageException - if:
        • size is greater than pixels.sizeX and pixels.sizeY
        • setPixelsId(long) has not yet been called
        See Also:
        getThumbnailDirect(Integer, Integer)

      • getThumbnailForSectionByLongestSideDirect

        byte[] getThumbnailForSectionByLongestSideDirect​(int theZ,
                                                 int theT,
                                                 java.lang.Integer size)
        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.
        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.
        Returns:
        a JPEG thumbnail byte buffer.
        Throws:
        ApiUsageException - if:
        • size is greater than pixels.sizeX and pixels.sizeY
        • setPixelsId(long) has not yet been called
        See Also:
        getThumbnailDirect(Integer, Integer)

      • createThumbnail

        void createThumbnail​(java.lang.Integer sizeX,
                     java.lang.Integer sizeY)
        Creates a thumbnail for a pixels set using a given set of rendering settings (RenderingDef) in the on-disk cache.
        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.
        Throws:
        ApiUsageException - if:
        • sizeX is greater than pixels.sizeX
        • sizeX is negative
        • sizeY is greater than pixels.sizeY
        • sizeY is negative
        • setPixelsId(long) has not yet been called
        See Also:
        getThumbnail(Integer, Integer), getThumbnailDirect(Integer, Integer)

      • createThumbnailsByLongestSideSet

        void createThumbnailsByLongestSideSet​(java.lang.Integer size,
                                      java.util.Set<java.lang.Long> pixelsIds)
        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 setPixelsId(long). 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.
        Throws:
        ApiUsageException - if:
        • size is greater than pixels.sizeX and pixels.sizeY
        • size is negative
        See Also:
        createThumbnail(Integer, Integer), createThumbnails()

      • thumbnailExists

        boolean thumbnailExists​(java.lang.Integer sizeX,
                        java.lang.Integer sizeY)
        Checks if a thumbnail of a particular size exists for a pixels set.
        Parameters:
        sizeX - the X-axis width of the thumbnail. null specifies use the default size of 48.
        sizeY - the Y-axis width of the thumbnail. null specifies user the default size of 48.
        Throws:
        ApiUsageException - if:
        See Also:
        getThumbnail(Integer, Integer), getThumbnailDirect(Integer, Integer)

      • resetDefaults

        void resetDefaults()
        Resets the rendering definition for the active pixels set to its default settings.