icy.sequence

Class SequenceBuilder

java.lang.Object

icy.sequence.SequenceBuilder

public class SequenceBuilder
extends java.lang.Object

This class is intended for plugins that construct new sequences by:
- first, specifying a data-type and a 5D-size for the sequence to be created
- second, visiting each sample (x,y,z,t,c) to set its value.

A typical example of such situation would be a plugin that take a sequence in input and return a copy of that sequence in output. For such plugins, the SequenceBuilder class provides some tools to ease the creation of the output sequence, especially in a multi-thread context. To cut a long story short, here is an example of how the above-mentioned copy algorithm could be implemented with SequenceBuilder:

   // Input sequence
   Sequence in = ...
   
   // Create a SequenceBuilder object, that will be in charge of allocating
   // and feeding the output sequence.
   SequenceBuilder builder = new SequenceBuilder
   (
     // The output sequence will have the same size and data-type than the input
     in.getSizeX(), in.getSizeY(), in.getSizeZ(), in.getSizeT(), in.getSizeC(),
     in.getDataType_()
   );
   
   // Start the building process.
   builder.beginUpdate();
   try
   {
     // Here, the copy can be multi-threaded. No synchronization or mutex-locking
     // is required on the side of the SequenceBuilder object.
     
     ...
     
     // Thread 1
     forall(int t,z,c in listOfXYPlanesToBeDoneByThread1)
     {
       // Retrieve the array that will hold the pixel values corresponding to
       // the XY-plane at coordinates (t, z, c) in the output sequence. If this
       // object does not exist, it is created. The object returned by the
       // method getData is actually an instance of byte[], short[], int[],
       // float[] or double[], depending on the data-type specified in the
       // SequenceBuilder constructor.
       // 
       // Remark: depending on the context, it may be more convenient to call
       // builder.getDataAsDouble, builder.getDataAsByte, etc...
       // 
       Object buffer = builder.getData(t, z, c);
       
       // Execute the copy. For example:
       { Array1DUtil.arrayToArray(in.getDataXY(t, z, c), buffer); }
       
       // Mark the array returned by the previous call to builder.getData(t, z, c)
       // as ready to be incorporated in the output sequence.
       // 
       // Remark: there should only be one call to the method validateData
       // per set of coordinates (t, z, c).
       //
       builder.validateData(t, z, c);
     }
     
     ...
     
     // Thread 2
     forall(int t,z,c in listOfXYPlanesToBeDoneByThread2) {
       // etc...
     }
     
     ...
     
   }
   
   // Finish the building process (each call to beginUpdate() must be followed
   // by a call to endUpdate()).
   finally {
     builder.endUpdate();
   }
   
   // Return the sequence that have been created by the SequenceBuilder object.
   return builder.getResult();
 

Author:

Yoann Le Montagner

Constructor Summary

Constructors

Constructor and Description
SequenceBuilder(int sizeX, int sizeY, int sizeZ, int sizeT, int sizeC, DataType dataType) Allocate a new sequence that will have the given size, dataType and an empty name
SequenceBuilder(int sizeX, int sizeY, int sizeZ, int sizeT, int sizeC, DataType dataType, Sequence target) If non-null, the 'target' argument will be used to store the result of the sequence building process, and no new sequence will be created.

Method Summary

Methods

Modifier and Type	Method and Description
void	beginUpdate() Start building the sequence
void	endUpdate() Finish building the sequence.
java.lang.Object	getData(int t, int z, int c) Retrieve or allocate the buffer for the XY plane corresponding to the given (t,z,c) coordinates
byte[]	getDataAsByte(int t, int z, int c) Retrieve or allocate the buffer for the XY plane corresponding to the given (t,z,c) coordinates
double[]	getDataAsDouble(int t, int z, int c) Retrieve or allocate the buffer for the XY plane corresponding to the given (t,z,c) coordinates
float[]	getDataAsFloat(int t, int z, int c) Retrieve or allocate the buffer for the XY plane corresponding to the given (t,z,c) coordinates
int[]	getDataAsInt(int t, int z, int c) Retrieve or allocate the buffer for the XY plane corresponding to the given (t,z,c) coordinates
short[]	getDataAsShort(int t, int z, int c) Retrieve or allocate the buffer for the XY plane corresponding to the given (t,z,c) coordinates
DataType	getDataType() Data-type of the sequence to be created
Sequence	getResult() Return the output sequence
int	getSizeC() Size C of the sequence to be created
int	getSizeT() Size T of the sequence to be created
int	getSizeX() Size X of the sequence to be created
int	getSizeY() Size Y of the sequence to be created
int	getSizeZ() Size Z of the sequence to be created
boolean	isPreAllocated() Check if the sequence is pre-allocated, i.e. if it already has the proper size and data-type that was specified by the argument passed to the SequenceBuilder constructor
void	validateData(int t, int z, int c) Validate the buffer for the XY plane corresponding to the given (t,z,c) coordinates

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SequenceBuilder

public SequenceBuilder(int sizeX,
               int sizeY,
               int sizeZ,
               int sizeT,
               int sizeC,
               DataType dataType)

Allocate a new sequence that will have the given size, dataType and an empty name

SequenceBuilder

public SequenceBuilder(int sizeX,
               int sizeY,
               int sizeZ,
               int sizeT,
               int sizeC,
               DataType dataType,
               Sequence target)

If non-null, the 'target' argument will be used to store the result of the sequence building process, and no new sequence will be created.

Two situations may occur:

The sequence 'target' has the same size and data-type than specified by the arguments passed to the SequenceBuilder object. In that case, no new buffer/image allocation is performed, and the sequence is only modified through calls to the method Sequence.getDataXY(). Otherwise, the sequence 'target' will be completly cleared (through a call to the method Sequence.removeAllImages()) when first calling the method SequenceBuilder.beginUpdate().

Method Detail

getSizeX

public int getSizeX()

Size X of the sequence to be created

getSizeY

public int getSizeY()

Size Y of the sequence to be created

getSizeZ

public int getSizeZ()

Size Z of the sequence to be created

getSizeT

public int getSizeT()

Size T of the sequence to be created

getSizeC

public int getSizeC()

Size C of the sequence to be created

getDataType

public DataType getDataType()

Data-type of the sequence to be created

getResult

public Sequence getResult()

Return the output sequence

isPreAllocated

public boolean isPreAllocated()

Check if the sequence is pre-allocated, i.e. if it already has the proper size and data-type that was specified by the argument passed to the SequenceBuilder constructor

beginUpdate

public void beginUpdate()

Start building the sequence

Throws:

java.lang.IllegalStateException - if the object is already in an "updating" state

endUpdate

public void endUpdate()

Finish building the sequence.
Nothing happens if beginUpdate() has not been called previously

getDataAsDouble

public double[] getDataAsDouble(int t,
                       int z,
                       int c)

Retrieve or allocate the buffer for the XY plane corresponding to the given (t,z,c) coordinates

Throws:

java.lang.NullPointerException - if the method beginUpdate() has not been called previously.

getDataAsFloat

public float[] getDataAsFloat(int t,
                     int z,
                     int c)

Retrieve or allocate the buffer for the XY plane corresponding to the given (t,z,c) coordinates

Throws:

java.lang.NullPointerException - if the method beginUpdate() has not been called previously.

getDataAsByte

public byte[] getDataAsByte(int t,
                   int z,
                   int c)

Retrieve or allocate the buffer for the XY plane corresponding to the given (t,z,c) coordinates

Throws:

java.lang.NullPointerException - if the method beginUpdate() has not been called previously.

getDataAsShort

public short[] getDataAsShort(int t,
                     int z,
                     int c)

Retrieve or allocate the buffer for the XY plane corresponding to the given (t,z,c) coordinates

Throws:

java.lang.NullPointerException - if the method beginUpdate() has not been called previously.

getDataAsInt

public int[] getDataAsInt(int t,
                 int z,
                 int c)

Retrieve or allocate the buffer for the XY plane corresponding to the given (t,z,c) coordinates

Throws:

java.lang.NullPointerException - if the method beginUpdate() has not been called previously.

getData

public java.lang.Object getData(int t,
                       int z,
                       int c)

Retrieve or allocate the buffer for the XY plane corresponding to the given (t,z,c) coordinates

Throws:

java.lang.NullPointerException - if the method beginUpdate() has not been called previously.

validateData

public void validateData(int t,
                int z,
                int c)

Validate the buffer for the XY plane corresponding to the given (t,z,c) coordinates

Throws:

java.lang.NullPointerException - if the method beginUpdate() has not been called previously.