Module org.apache.sis.referencing
Package org.apache.sis.referencing.cs

# Interface AxisFilter

All Known Implementing Classes:
  `AxesConvention`

public interface AxisFilter
Modifications to apply on the axes of a coordinate system in order to produce a new coordinate system. `AxisFilter` can specify the axes to exclude in the new coordinate system, or specify different units and directions associated to the axes.
Terminology note the word “filter” is understood here as “a computer program or subroutine to process a stream, producing another stream” (Wikipedia).

Note that filtering one or more axes may result in a change of coordinate system type. For example, excluding the z axis of a cylindrical coordinate system results in a polar coordinate system.

## Default implementation

All methods in this interface have a default implementation equivalent to no-operation. Implementers need to override only the methods for the aspects to change.

## Limitations

This interface is not for changing axis order. For changing axis order in addition to axis directions or units, see `AxesConvention`.

Since:
  0.6
See Also:
  - `CoordinateSystems​.replaceAxes(CoordinateSystem, AxisFilter)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default boolean`
  `accept(CoordinateSystemAxis axis)`
  Returns `true` if the given axis shall be included in the new coordinate system.
  `default AxisDirection`
  `getDirectionReplacement(CoordinateSystemAxis axis, AxisDirection direction)`
  Returns a replacement for the given axis direction.
  `default Unit<?>`
  `getUnitReplacement(CoordinateSystemAxis axis, Unit<?> unit)`
  Returns a replacement for the given axis unit.

- ## Method Details

  - ### accept

    default boolean accept(CoordinateSystemAxis axis)
    Returns `true` if the given axis shall be included in the new coordinate system. The default implementation unconditionally returns `true`.
    Parameters:
      `axis` - the axis to test.
    Returns:
      `true` if the given axis shall be included in the new coordinate system.

  - ### getDirectionReplacement

    default AxisDirection getDirectionReplacement(CoordinateSystemAxis axis, AxisDirection direction)
    Returns a replacement for the given axis direction. The default implementation unconditionally returns the given `direction` unchanged.

    #### Example

    For forcing the direction of the z axis toward up while leaving other axes unchanged, one can write:

            @Override
            public getDirectionReplacement(CoordinateSystemAxis axis, AxisDirection direction) {
                if (direction == AxisDirection.DOWN) {
                    direction = AxisDirection.UP;
                }
                return direction;
            }

    Parameters:
      `axis` - the axis for which to change axis direction, if desired.
      `direction` - the original axis direction.
    Returns:
      the new axis direction, or `direction` if there is no change.
    Since:
      0.7

  - ### getUnitReplacement

    default Unit<?> getUnitReplacement(CoordinateSystemAxis axis, Unit<?> unit)
    Returns a replacement for the given axis unit. The default implementation unconditionally returns the given `unit` unchanged.

    #### Example

    For replacing all angular units of a coordinate system to degrees (regardless what the original angular units were) while leaving other kinds of units unchanged, one can write:

            @Override
            public Unit<?> getUnitReplacement(CoordinateSystemAxis axis, Unit<?> unit) {
                if (Units.isAngular(unit)) {
                    unit = Units.DEGREE;
                }
                return unit;
            }

    Parameters:
      `axis` - the axis for which to change unit, if desired.
      `unit` - the original axis unit.
    Returns:
      the new axis unit, or `unit` if there is no change.
    Since:
      0.7