RawPixelsStore.java

/*
 *   ome.api.RawPixelsStore
 *
 *   Copyright 2006 University of Dundee. All rights reserved.
 *   Use is subject to license terms supplied in LICENSE.txt
 */

package ome.api;

import java.util.List;
import java.util.Map;
import java.util.Set;

import ome.annotations.Validate;
import ome.model.core.Pixels;
import omeis.providers.re.data.PlaneDef;

/**
 * Binary data provider. Initialized with the id of a
 * {@link ome.model.core.Pixels} instance, this interface 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 {@link #getByteWidth()}, {@link #isFloat()}, and
 * {@link #isSigned()}.
 */
public interface RawPixelsStore extends StatefulServiceInterface {

    // State management.
    /**
     * Initializes the stateful service for a given Pixels set.
     * @param pixelsId Pixels set identifier.
     * @param bypassOriginalFile Whether or not to bypass checking for an
     * original file to back the pixel buffer used by this service. If requests
     * are predominantly <code>write-only</code> or involve the population of
     * a brand new pixel buffer using <code>true</code> here is a safe
     * optimization otherwise <code>false</code> is expected.
     */
    public void setPixelsId(long pixelsId, boolean bypassOriginalFile);
    
    /**
     * Returns the current Pixels path.
     * @return See above.
     */
    public String getPixelsPath();

    /**
     * Returns the current Pixels set identifier.
     * @return See above.
     */
    public long getPixelsId();

    /**
     * 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. 
     * @param pixelsIds Pixels IDs to cache.
     */
    public void prepare(@Validate(Long.class) Set<Long> pixelsIds);

    /**
     * Returns the plane size
     * @return the plane size
     */
    public long getPlaneSize();

    public int getRowSize();

    public long getStackSize();

    public long getTimepointSize();

    public long getTotalSize();

    public long getRowOffset(int y, int z, int c, int t);

    public long getPlaneOffset(int z, int c, int t);

    public long getStackOffset(int c, int t);

    public long getTimepointOffset(int t);

    public byte[] getTile(int z, int c, int t, int x, int y, int w, int h);

    public byte[] getRegion(int size, long offset);
    
    public byte[] getRow(int y, int z, int c, int t);
    
    public byte[] getCol(int x, int z, int c, int t);
    
    public Map<Integer, int[]> getHistogram(int[] channels, int binCount, boolean globalRange, PlaneDef plane);
    
    public Map<Integer, double[]> findMinMax(int[] channels);
    
    public byte[] getHypercube(@Validate(Integer.class) List<Integer> offset, @Validate(Integer.class) List<Integer> size, @Validate(Integer.class) List<Integer> step);

    public byte[] getPlaneRegion(int z, int c, int t, int count, int offset);

    public byte[] getPlane(int z, int c, int t);

    public byte[] getStack(int c, int t);

    public byte[] getTimepoint(int t);

    public void setTile(byte[] buffer, int z, int c, int t, int x, int y, int w, int h);

    public void setRegion(int size, long offset, byte[] buffer);

    public void setRow(byte[] buffer, int y, int z, int c, int t);

    public void setPlane(byte[] buffer, int z, int c, int t);

    public void setStack(byte[] buffer, int z, int c, int t);

    public void setTimepoint(byte[] buffer, int t);

    public int getByteWidth();

    public boolean isSigned();

    public boolean isFloat();

    public byte[] calculateMessageDigest();

    public Pixels save();

    public boolean requiresPixelsPyramid();

    public Object getResolutionDescriptions();

    /**
     * Retrieves the number of resolution levels that the backing
     * pixels pyramid contains.
     * @return The number of resolution levels. This value does not
     * necessarily indicate either the presence or absence of a
     * pixels pyramid.
     **/
    public int getResolutionLevels();

    /**
     * Retrieves the active resolution level.
     * @return The active resolution level.  The level will be non-negative and less
     * than {@link #getResolutionLevels()}.  Resolution level 0 is the smallest
     * resolution and resolution level <code>getResolutionLevels() - 1</code>
     * is the largest resolution.  This is the inverse of how Bio-Formats indexes
     * resolutions.
     */
    public int getResolutionLevel();

    /**
     * Sets the active resolution level.
     * @param resolutionLevel The resolution level to be used.
     * The level should be non-negative and less than
     * {@link #getResolutionLevels()}.  * Resolution level 0 is the smallest
     * resolution and resolution level <code>getResolutionLevels() - 1</code>
     * is the largest resolution.  This is the inverse of how Bio-Formats indexes
     * resolutions.
     */
    public void setResolutionLevel(int resolutionLevel);

    public int[] getTileSize();

}