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.

Icy Developer Documentation

Class SequenceBuilder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

SequenceBuilder

SequenceBuilder

Method Detail

getSizeX

getSizeY

getSizeZ

getSizeT

getSizeC

getDataType

getResult

isPreAllocated

beginUpdate

endUpdate

getDataAsDouble

getDataAsFloat

getDataAsByte

getDataAsShort

getDataAsInt

getData

validateData

Icy Developer Documentation