org.apache.sis.referencing.operation.transform

## Class TransformSeparator

- Object
- - TransformSeparator

-     public class TransformSeparator
      extends Object

  Extracts a sub-transform from a given `MathTransform` and source or target dimension indices. Given an arbitrary `MathTransform`, this class tries to return a new math transform that operates only on a given set of source or target dimensions.
  Example: if the supplied `transform` has (x,y,z) inputs and (λ,φ,h) outputs, then the following code:

      TransformSeparator s = new TransformSeparator(theTransform);
      s.addSourceDimensionRange(0, 2);
      MathTransform mt = s.separate();

  will return a transform with (x,y) inputs and (probably) (λ,φ) outputs. The output dimensions can be verified with a call to `getTargetDimensions()`.
  Since:
    0.7

  Defined in the `sis-referencing` module

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected MathTransformFactory` | `factory` The factory to use for creating new math transforms.
    `protected int[]` | `sourceDimensions` Indices of transform input dimensions to keep, or `null` if not yet defined.
    `protected int[]` | `targetDimensions` Indices of transform output dimensions to keep, or `null` if not yet defined.
    `protected MathTransform` | `transform` The transform to separate.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TransformSeparator(MathTransform transform)` Constructs a separator for the given transform.
    `TransformSeparator(MathTransform transform, MathTransformFactory factory)` Constructs a separator for the given transform and using the given factory.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addSourceDimensionRange(int lower, int upper)` Adds a range of input dimensions to keep in the separated transform.
    `void` | `addSourceDimensions(int... dimensions)` Adds input dimensions to keep in the separated transform.
    `void` | `addTargetDimensionRange(int lower, int upper)` Adds a range of output dimensions to keep in the separated transform.
    `void` | `addTargetDimensions(int... dimensions)` Adds output dimensions to keep in the separated transform.
    `void` | `clear()` Clears any source and target dimension settings.
    `protected MathTransform` | `filterSourceDimensions(MathTransform step, int[] dimensions)` Creates a transform for the same mathematic than the given `step` but expecting only the given dimensions as inputs.
    `protected MathTransform` | `filterTargetDimensions(MathTransform step, int[] dimensions)` Creates a transform for the same mathematic than the given `step` but producing only the given dimensions as outputs.
    `int[]` | `getSourceDimensions()` Returns the input dimensions to keep or kept in the separated transform.
    `int[]` | `getTargetDimensions()` Returns the output dimensions to keep or kept in the separated transform.
    `MathTransform` | `separate()` Separates the math transform specified at construction time for given dimension indices.

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### transform

          protected final MathTransform transform

      The transform to separate.

    - #### sourceDimensions

          protected int[] sourceDimensions

      Indices of transform input dimensions to keep, or `null` if not yet defined. If non-null, the indices in the array must be sorted in strictly increasing order. This sequence can contain any integers in the range 0 inclusive to `MathTransform​.getSourceDimensions()` exclusive.

      Values in this array should never be modified. For adding, removing or editing indices, new arrays should be created and assigned to this field. This approach makes easier to keep snapshots of indices arrays at various stages during the process of separating a `MathTransform`.

      See Also:
        `getSourceDimensions()`, `addSourceDimensions(int...)`, `addSourceDimensionRange(int, int)`

    - #### targetDimensions

          protected int[] targetDimensions

      Indices of transform output dimensions to keep, or `null` if not yet defined. If non-null, the indices in the array must be sorted in strictly increasing order. This sequence can contain any integers in the range 0 inclusive to `MathTransform​.getTargetDimensions()` exclusive.

      Values in this array should never be modified. For adding, removing or editing indices, new arrays should be created and assigned to this field. This approach makes easier to keep snapshots of indices arrays at various stages during the process of separating a `MathTransform`.

      See Also:
        `getTargetDimensions()`, `addTargetDimensions(int...)`, `addTargetDimensionRange(int, int)`

    - #### factory

          protected final MathTransformFactory factory

      The factory to use for creating new math transforms.

  - ### Constructor Detail

    - #### TransformSeparator

          public TransformSeparator(MathTransform transform)

      Constructs a separator for the given transform.
      Parameters:
        `transform` - the transform to separate.

    - #### TransformSeparator

          public TransformSeparator(MathTransform transform,
                                    MathTransformFactory factory)

      Constructs a separator for the given transform and using the given factory.
      Parameters:
        `transform` - the transform to separate.
        `factory` - the factory to use for creating new math transforms.

  - ### Method Detail

    - #### clear

          public void clear()

      Clears any source and target dimension settings. This method can be invoked when the same `MathTransform` needs to be separated in more than one part, for example an horizontal and a vertical component.

    - #### addSourceDimensions

          public void addSourceDimensions(int... dimensions)
                                   throws IllegalArgumentException

      Adds input dimensions to keep in the separated transform. The given values are source dimension indices of the transform given to the constructor.

      Constraints:

      - All numbers shall be in the range 0 inclusive to `MathTransform​.getSourceDimensions()` exclusive.
      - The `dimensions` values shall be in strictly increasing order.
      - The `dimensions` values shall be greater than all values specified by all previous calls of this method since construction or since the last call to `clear()`.
      Parameters:
        `dimensions` - a sequence of source dimensions to keep, in strictly increasing order.
      Throws:
        `IllegalArgumentException` - if `dimensions` contains negative values or if values are not in a strictly increasing order.

    - #### addSourceDimensionRange

          public void addSourceDimensionRange(int lower,
                                              int upper)
                                       throws IllegalArgumentException

      Adds a range of input dimensions to keep in the separated transform. The `lower` and `upper` values define a range of source dimension indices of the transform given to the constructor.
      Parameters:
        `lower` - the lower dimension, inclusive. Shall not be smaller than 0.
        `upper` - the upper dimension, exclusive. Shall be smaller than `MathTransform​.getSourceDimensions()`.
      Throws:
        `IllegalArgumentException` - if `lower` or `upper` are out of bounds.

    - #### getSourceDimensions

          public int[] getSourceDimensions()
                                    throws IllegalStateException

      Returns the input dimensions to keep or kept in the separated transform. This method performs the first applicable action in the following list:
      1. Source dimensions have been explicitly set by at least one call to `addSourceDimensions(int...)` or `addSourceDimensionRange(int, int)` since construction or since last call to `clear()`. In such case, this method returns all specified source dimensions.
      2. No source dimensions were set but `separate()` has been invoked. In such case, this method returns the sequence of source dimensions that `separate()` chooses to retain. It is often, but not necessarily, all source dimensions of the transform given at construction time.
      3. Otherwise an exception is thrown.
      Returns:
        the input dimension as a sequence of strictly increasing values.
      Throws:
        `IllegalStateException` - if input dimensions have not been set and `separate()` has not yet been invoked.

    - #### addTargetDimensions

          public void addTargetDimensions(int... dimensions)
                                   throws IllegalArgumentException

      Adds output dimensions to keep in the separated transform. The given values are target dimension indices of the transform given to the constructor.

      Constraints:

      - All numbers shall be in the range 0 inclusive to `MathTransform​.getTargetDimensions()` exclusive.
      - The `dimensions` values shall be in strictly increasing order.
      - The `dimensions` values shall be greater than all values specified by all previous calls of this method since construction or since the last call to `clear()`.
      Parameters:
        `dimensions` - a sequence of target dimensions to keep, in strictly increasing order.
      Throws:
        `IllegalArgumentException` - if `dimensions` contains negative values or if values are not in a strictly increasing order.

    - #### addTargetDimensionRange

          public void addTargetDimensionRange(int lower,
                                              int upper)
                                       throws IllegalArgumentException

      Adds a range of output dimensions to keep in the separated transform. The `lower` and `upper` values define a range of target dimension indices of the transform given to the constructor.
      Parameters:
        `lower` - the lower dimension, inclusive. Shall not be smaller than 0.
        `upper` - the upper dimension, exclusive. Shall be smaller than `MathTransform​.getTargetDimensions()`.
      Throws:
        `IllegalArgumentException` - if `lower` or `upper` are out of bounds.

    - #### getTargetDimensions

          public int[] getTargetDimensions()
                                    throws IllegalStateException

      Returns the output dimensions to keep or kept in the separated transform. This method performs the first applicable action in the following list:
      1. Target dimensions have been explicitly set by at least one call to `addTargetDimensions(int...)` or `addTargetDimensionRange(int, int)` since construction or since last call to `clear()`. In such case, this method returns all specified target dimensions.
      2. No target dimensions were set but `separate()` has been invoked. In such case, the target dimensions are inferred automatically from the source dimensions and the transform.
      3. Otherwise an exception is thrown.
      Returns:
        the output dimension as a sequence of strictly increasing values.
      Throws:
        `IllegalStateException` - if output dimensions have not been set and `separate()` has not yet been invoked.

    - #### separate

          public MathTransform separate()
                                 throws FactoryException

      Separates the math transform specified at construction time for given dimension indices. This method creates a math transform that use only the specified source dimensions and return only the specified target dimensions. If the source or target dimensions were not specified, then they will be inferred as below:
      - If source dimensions were unspecified, then the returned transform will keep at least all source dimensions needed for computing the specified target dimensions. In many cases the returned transform unconditionally keep all source dimensions, but not necessarily. If all source dimensions need to be kept, it is better to specify that explicitely.
      - If target dimensions were unspecified, then the returned transform will expect only the specified source dimensions as inputs, and the target dimensions will be inferred automatically.
      The source and target dimensions actually used can be queried by calls to `getSourceDimensions()` or `getTargetDimensions()` after this `separate()` method.
      Returns:
        the separated math transform.
      Throws:
        `FactoryException` - if the transform can not be separated.

    - #### filterSourceDimensions

          protected MathTransform filterSourceDimensions(MathTransform step,
                                                         int[] dimensions)
                                                  throws FactoryException

      Creates a transform for the same mathematic than the given `step` but expecting only the given dimensions as inputs. This method is invoked by `separate()` when user-specified source dimensions need to be taken in account. The given `step` and `dimensions` are typically the values of `transform` and `sourceDimensions` fields respectively, but not necessarily. In particular those arguments will differ when this method is invoked recursively for processing concatenated or sub-transforms.

      Subclasses can override this method if they need to handle some `MathTransform` implementations in a special way. However all implementations of this method shall obey to the following contract:

      - `sourceDimensions` and `targetDimensions` should not be assumed accurate since they may be temporarily outdated or modified during recursive calls to this method.
      - `sourceDimensions` should not be modified by this method.
      - `targetDimensions` must be overwritten (not updated) by this method to the sequence of all target dimensions of `step` that are also target dimensions of the returned transform. The indices shall be in strictly increasing order from 0 inclusive to `step​.getTargetDimensions()` exclusive.
      Parameters:
        `step` - the transform for which to retain only a subset of the source dimensions.
        `dimensions` - indices of the source dimensions of `step` to retain.
      Returns:
        a transform expecting only the given source dimensions.
      Throws:
        `FactoryException` - if the given transform is not separable.

    - #### filterTargetDimensions

          protected MathTransform filterTargetDimensions(MathTransform step,
                                                         int[] dimensions)
                                                  throws FactoryException

      Creates a transform for the same mathematic than the given `step` but producing only the given dimensions as outputs. This method is invoked by `separate()` when user-specified target dimensions need to be taken in account. The given `step` and `dimensions` are typically the values of `transform` and `targetDimensions` fields respectively, but not necessarily.

      Subclasses can override this method if they need to handle some `MathTransform` implementations in a special way. However all implementations of this method shall obey to the following contract:

      - `sourceDimensions` and `targetDimensions` should not be assumed accurate.
      - `sourceDimensions` should not be modified by this method.
      - `targetDimensions` should not be modified by this method.
      The number and nature of inputs stay unchanged. For example if the supplied `transform` has (longitude, latitude, height) outputs, then a filtered transform may keep only the (longitude, latitude) part for the same inputs. In most cases, the filtered transform is non-invertible since it loose informations.
      Parameters:
        `step` - the transform for which to retain only a subset of the target dimensions.
        `dimensions` - indices of the target dimensions of `step` to retain.
      Returns:
        a transform producing only the given target dimensions.
      Throws:
        `FactoryException` - if the given transform is not separable.

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.