# 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