# Interface Projection

All Known Implementing Classes:
  `FixedSkyviewProjection, HemisphereProjection, SinProjection, SkyviewProjection`

public interface Projection
Sky projection. Defines the mapping of normalised X,Y,Z coordinates (direction cosines) to dimensionless coordinates on a 2D plane.

Since:
  21 Feb 2013
Author:
  Mark Taylor

## Method Summary

Modifier and Type
Method
Description
`SkyAspect`
`createAspect(boolean reflect, double[] r3, double radiusRad, Range[] vxyzRanges)`
Creates a SkyAspect from configuration information.
`double[]`
`cursorRotate(double[] rotmat, Point2D.Double pos0, Point2D.Double pos1)`
Attempts to return a rotation matrix corresponding to moving the cursor between two plane positions.
`SkyFov`
`getFov(SkySurface surf)`
Returns the field of view represented by this aspect.
`String`
`getProjectionDescription()`
Returns a short description of the projection.
`String`
`getProjectionName()`
Returns the projection name.
`Shape`
`getProjectionShape()`
Returns the shape which encloses all the plane positions to which legal sky coordinates can be projected.
`boolean`
`isContinuous()`
Indicates whether this projection is known to be continous over its whole range.
`boolean`
`isContinuousLine(double[] r3a, double[] r3b)`
Indicates whether a line between the two given sky positions is (believed to be) continuous.
`boolean`
`project(double rx, double ry, double rz, Point2D.Double pos)`
Transforms a sky position to a plane position.
`double[]`
`projRotate(double[] rotmat, Point2D.Double pos0, Point2D.Double pos1)`
Attempts to return a rotation matrix that will transform a sky position from one plane position to another.
`boolean`
`unproject(Point2D.Double pos, double[] r3)`
Transforms a plane position to a sky position.
`boolean`
`useRanges(boolean reflect, double[] r3, double radiusRad)`
Indicates whether ranges should be provided to generate a SkyAspect.

## Method Details

### getProjectionName

String getProjectionName()
Returns the projection name.

Returns:
  user-directed projection name

### getProjectionDescription

String getProjectionDescription()
Returns a short description of the projection. return projection description

### isContinuous

boolean isContinuous()
Indicates whether this projection is known to be continous over its whole range. Returns false if there may be any cases for which `isContinuousLine` returns false.

Returns:
  true iff this projection is known to be continuous

### isContinuousLine

boolean isContinuousLine(double[] r3a, double[] r3b)
Indicates whether a line between the two given sky positions is (believed to be) continuous. "Line" in this context should ideally be interpreted as the shorter arc on a great circle. A line crossing lon=180 for instance would be discontinuous in an Aitoff projection, but not in a Sin projection.

Parameters:
  `r3a` - 3-element array giving normalised X,Y,Z coordinates of line start
  `r3b` - 3-element array giving normalised X,Y,Z coordinates of line end
Returns:
  true if line is believed to be continuous; if in doubt, probably better to return true

### project

boolean project(double rx, double ry, double rz, Point2D.Double pos)
Transforms a sky position to a plane position.

Parameters:
  `rx` - normalised 3D X coordinate
  `ry` - normalised 3D Y coordinate
  `rz` - normalised 3D Z coordinate
  `pos` - point object into which projected dimensionless X,Y coordinates will be written on success
Returns:
  true if transformation succeeded

### unproject

boolean unproject(Point2D.Double pos, double[] r3)
Transforms a plane position to a sky position.

Parameters:
  `pos` - contains dimensionless X,Y coordinates of plane position
  `r3` - 3-element array into which normalised X,Y,Z sky coordinates will be written on success
Returns:
  true if transformation succeeded

### getProjectionShape

Shape getProjectionShape()
Returns the shape which encloses all the plane positions to which legal sky coordinates can be projected. Typically this has linear dimensions of the order of PI.

Returns:
  projected sky shape

### cursorRotate

double[] cursorRotate(double[] rotmat, Point2D.Double pos0, Point2D.Double pos1)
Attempts to return a rotation matrix corresponding to moving the cursor between two plane positions. Ideally this should do the same thing as `projRotate`, for both positions on the sky, and provide some other intuitive behaviour if one or both is out of the projection range.

Null may be returned if this projection does not support rotation.

Parameters:
  `rotmat` - initial rotation matrix
  `pos0` - initial cursor position
  `pos1` - destination cursor position
Returns:
  destination rotation matrix, or null

### projRotate

double[] projRotate(double[] rotmat, Point2D.Double pos0, Point2D.Double pos1)
Attempts to return a rotation matrix that will transform a sky position from one plane position to another.

Consider a sky point S, rotated by an initial rotation matrix `rotmat` to S', which when projected by this projection lands on the plane at `pos0`. This method attempts to determine a rotation matrix which when used instead of `rotmat` would end up with the rotated and projected point at `pos1`.

Null may be returned if this projection does not support projection.

Parameters:
  `rotmat` - initial rotation matrix
  `pos0` - initial projected position
  `pos1` - destination projected position
Returns:
  destination rotation matrix, or null

### useRanges

boolean useRanges(boolean reflect, double[] r3, double radiusRad)
Indicates whether ranges should be provided to generate a SkyAspect. If supplied field of view arguments are sufficient, or if a default aspect is always produced, return false.

Parameters:
  `reflect` - whether requested aspect will be reflected
  `r3` - central position of field of view (may be null)
  `radiusRad` - radius of field of view (may be NaN)
Returns:
  true if ranges would be useful given the other arguments
See Also:
  - `SurfaceFactory.readRanges(P, PlotLayer[], DataStore)`

### createAspect

SkyAspect createAspect(boolean reflect, double[] r3, double radiusRad, Range[] vxyzRanges)
Creates a SkyAspect from configuration information. Either the supplied field of view or data ranges may be used, or neither.

Parameters:
  `reflect` - whether requested aspect will be reflected
  `r3` - central position of field of view (may be null)
  `radiusRad` - radius of field of view (may be NaN)
  `vxyzRanges` - definite ranges for normalised X,Y,Z coordinates acquired from data
Returns:
  new sky aspect
See Also:
  - `SurfaceFactory.createAspect(P, ConfigMap, Range[])`

### getFov

SkyFov getFov(SkySurface surf)
Returns the field of view represented by this aspect. This is a best estimate, it may be approximate depending on the projection geometry. If the field of view is the default for this projection, then null should be returned. Null may also be returned if for some reason no field of view can be determined.

Parameters:
  `surf` - sky surface, which must be set up using this projection
Returns:
  field of view, or null