CubeSurfaceFactory (Starlink-UK API)

java.lang.Object
- uk.ac.starlink.ttools.plot2.geom.CubeSurfaceFactory

All Implemented Interfaces:

SurfaceFactory<CubeSurfaceFactory.Profile,CubeAspect>
```
public class CubeSurfaceFactory
extends Object
implements SurfaceFactory<CubeSurfaceFactory.Profile,CubeAspect>
```
Surface factory for 3-d plotting.
This can be used in one of two modes (determined at construction time), isotropic and non-isotropic. In isotropic mode, the scaling on each of the 3 axes is the same, and in non-isotropic mode they can vary independently of each other. The profile and aspect configuration keys (that is, the user interface) are different according to which mode is in effect, but the actual surfaces generated are the same either way, undistinguished instances of CubeSurface.

Since:

20 Feb 2013

Author:

Mark Taylor

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`CubeSurfaceFactory.Profile` Profile class which defines fixed configuration items for an isotropic or non-isotropic CubeSurface.

Field Summary

Fields
Modifier and Type	Field and Description
`static ConfigKey<Boolean>`	`FRAME_KEY` Config key for whether to draw axis wire frame.
`static double`	`ISO_CENTER_TOLERANCE` Proportional auto-ranging isotropic snap-to-origin threshold.
`static ConfigKey<Double>`	`ISOCROWD_KEY` Config key for isotropic tick mark crowding.
`static ConfigKey<Double>`	`PHI_KEY` Config key for first Euler angle of rotation, units of degrees.
`static ConfigKey<Double>`	`PSI_KEY` Config key for third Euler angle of rotation, units of degrees.
`static ConfigKey<Double>`	`SCALE_KEY` Config key for cube edge length (isotropic only).
`static ConfigKey<Double>`	`THETA_KEY` Config key for second Euler angle of rotation, units of degrees.
`static ConfigKey<Double>`	`XC_KEY` Config key for X axis central position key (isotropic only).
`static ConfigKey<Double>`	`XCROWD_KEY` Config key for X axis tick mark crowding.
`static ConfigKey<Boolean>`	`XFLIP_KEY` Config key for X axis flip flag.
`static ConfigKey<String>`	`XLABEL_KEY` Config key for X axis text label.
`static ConfigKey<Boolean>`	`XLOG_KEY` Config key for X axis log scale flag.
`static ConfigKey<Double>`	`XMAX_KEY` Config key for X axis upper bound, before subranging.
`static ConfigKey<Double>`	`XMIN_KEY` Config key for X axis lower bound, before subranging.
`static ConfigKey<Double>`	`XOFF_KEY` Config key for graphics X offset, units of 1/2 screen size.
`static ConfigKey<Subrange>`	`XSUBRANGE_KEY` Config key for X axis subrange.
`static ConfigKey<Double>`	`YC_KEY` Config key for Y axis central position key (isotropic only).
`static ConfigKey<Double>`	`YCROWD_KEY` Config key for Y axis tick mark crowding.
`static ConfigKey<Boolean>`	`YFLIP_KEY` Config key for Y axis flip flag.
`static ConfigKey<String>`	`YLABEL_KEY` Config key for Y axis text label.
`static ConfigKey<Boolean>`	`YLOG_KEY` Config key for Y axis log scale flag.
`static ConfigKey<Double>`	`YMAX_KEY` Config key for Y axis upper bound, before subranging.
`static ConfigKey<Double>`	`YMIN_KEY` Config key for Y axis lower bound, before subranging.
`static ConfigKey<Double>`	`YOFF_KEY` Config key for graphics Y offset, units of 1/2 screen size.
`static ConfigKey<Subrange>`	`YSUBRANGE_KEY` Config key for Y axis subrange.
`static ConfigKey<Double>`	`ZC_KEY` Config key for Z axis central position key (isotropic only).
`static ConfigKey<Double>`	`ZCROWD_KEY` Config key for Z axis tick mark crowding.
`static ConfigKey<Boolean>`	`ZFLIP_KEY` Config key for Z axis flip flag.
`static ConfigKey<String>`	`ZLABEL_KEY` Config key for Z axis text label.
`static ConfigKey<Boolean>`	`ZLOG_KEY` Config key for Z axis log scale flag.
`static ConfigKey<Double>`	`ZMAX_KEY` Config key for Z axis upper bound, before subranging.
`static ConfigKey<Double>`	`ZMIN_KEY` Config key for Z axis lower bound, before subranging.
`static ConfigKey<Double>`	`ZOOM_KEY` Config key for zoom factor.
`static ConfigKey<Subrange>`	`ZSUBRANGE_KEY` Config key for Z axis subrange.

Constructor Summary

Constructors
Constructor and Description

CubeSurfaceFactory(boolean isIso)
Constructs an isotropic or non-isotropic cube surface factory.

Constructors
Constructor and Description
`CubeSurfaceFactory(boolean isIso)` Constructs an isotropic or non-isotropic cube surface factory.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`CubeAspect`	`createAspect(CubeSurfaceFactory.Profile profile, ConfigMap config, Range[] ranges)` Creates an aspect from configuration information.
`Navigator<CubeAspect>`	`createNavigator(ConfigMap navConfig)` Creates a navigator from configuration information.
`CubeSurfaceFactory.Profile`	`createProfile(ConfigMap config)` Creates a profile that can be used when creating a plot surface.
`Surface`	`createSurface(Rectangle plotBounds, CubeSurfaceFactory.Profile profile, CubeAspect aspect)` Returns a new plot surface.
`static double[]`	`eulerToRotationDegrees(double[] eulers)` Converts three ZXZ Euler angles to a rotation matrix.
`ConfigMap`	`getAspectConfig(Surface surface)` Returns a ConfigMap that corresponds to the configuration of the given surface, which must have been created by this factory.
`ConfigKey<?>[]`	`getAspectKeys()` Returns the configuration keys that may be used to configure aspect for this surface factory.
`ConfigKey<?>[]`	`getNavigatorKeys()` Returns the configuration keys that may be used to configure a navigator for use with this surface factory.
`PlotMetric`	`getPlotMetric()` Returns null.
`ConfigKey<?>[]`	`getProfileKeys()` Returns the configuration keys used to configure profile for this surface factory.
`static double[]`	`getRotation(ConfigMap config)` Reads the intended rotation matrix from a configuration map.
`Range[]`	`readRanges(CubeSurfaceFactory.Profile profile, PlotLayer[] layers, DataStore dataStore)` Provides the ranges that may be passed to `createAspect`.
`static double[]`	`rotationToEulerDegrees(double[] rotmat)` Converts rotation matrix to three ZXZ Euler angles in degrees.
`boolean`	`useRanges(CubeSurfaceFactory.Profile profile, ConfigMap config)` Indicates whether ranges should be provided to generate an aspect.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - XLOG_KEY
```
public static final ConfigKey<Boolean> XLOG_KEY
```
    Config key for X axis log scale flag.
  - YLOG_KEY
```
public static final ConfigKey<Boolean> YLOG_KEY
```
    Config key for Y axis log scale flag.
  - ZLOG_KEY
```
public static final ConfigKey<Boolean> ZLOG_KEY
```
    Config key for Z axis log scale flag.
  - XFLIP_KEY
```
public static final ConfigKey<Boolean> XFLIP_KEY
```
    Config key for X axis flip flag.
  - YFLIP_KEY
```
public static final ConfigKey<Boolean> YFLIP_KEY
```
    Config key for Y axis flip flag.
  - ZFLIP_KEY
```
public static final ConfigKey<Boolean> ZFLIP_KEY
```
    Config key for Z axis flip flag.
  - XLABEL_KEY
```
public static final ConfigKey<String> XLABEL_KEY
```
    Config key for X axis text label.
  - YLABEL_KEY
```
public static final ConfigKey<String> YLABEL_KEY
```
    Config key for Y axis text label.
  - ZLABEL_KEY
```
public static final ConfigKey<String> ZLABEL_KEY
```
    Config key for Z axis text label.
  - FRAME_KEY
```
public static final ConfigKey<Boolean> FRAME_KEY
```
    Config key for whether to draw axis wire frame.
  - XCROWD_KEY
```
public static final ConfigKey<Double> XCROWD_KEY
```
    Config key for X axis tick mark crowding.
  - YCROWD_KEY
```
public static final ConfigKey<Double> YCROWD_KEY
```
    Config key for Y axis tick mark crowding.
  - ZCROWD_KEY
```
public static final ConfigKey<Double> ZCROWD_KEY
```
    Config key for Z axis tick mark crowding.
  - ISOCROWD_KEY
```
public static final ConfigKey<Double> ISOCROWD_KEY
```
    Config key for isotropic tick mark crowding.
  - XMIN_KEY
```
public static final ConfigKey<Double> XMIN_KEY
```
    Config key for X axis lower bound, before subranging.
  - XMAX_KEY
```
public static final ConfigKey<Double> XMAX_KEY
```
    Config key for X axis upper bound, before subranging.
  - XSUBRANGE_KEY
```
public static final ConfigKey<Subrange> XSUBRANGE_KEY
```
    Config key for X axis subrange.
  - YMIN_KEY
```
public static final ConfigKey<Double> YMIN_KEY
```
    Config key for Y axis lower bound, before subranging.
  - YMAX_KEY
```
public static final ConfigKey<Double> YMAX_KEY
```
    Config key for Y axis upper bound, before subranging.
  - YSUBRANGE_KEY
```
public static final ConfigKey<Subrange> YSUBRANGE_KEY
```
    Config key for Y axis subrange.
  - ZMIN_KEY
```
public static final ConfigKey<Double> ZMIN_KEY
```
    Config key for Z axis lower bound, before subranging.
  - ZMAX_KEY
```
public static final ConfigKey<Double> ZMAX_KEY
```
    Config key for Z axis upper bound, before subranging.
  - ZSUBRANGE_KEY
```
public static final ConfigKey<Subrange> ZSUBRANGE_KEY
```
    Config key for Z axis subrange.
  - XC_KEY
```
public static final ConfigKey<Double> XC_KEY
```
    Config key for X axis central position key (isotropic only).
  - YC_KEY
```
public static final ConfigKey<Double> YC_KEY
```
    Config key for Y axis central position key (isotropic only).
  - ZC_KEY
```
public static final ConfigKey<Double> ZC_KEY
```
    Config key for Z axis central position key (isotropic only).
  - SCALE_KEY
```
public static final ConfigKey<Double> SCALE_KEY
```
    Config key for cube edge length (isotropic only).
  - PHI_KEY
```
public static final ConfigKey<Double> PHI_KEY
```
    Config key for first Euler angle of rotation, units of degrees.
  - THETA_KEY
```
public static final ConfigKey<Double> THETA_KEY
```
    Config key for second Euler angle of rotation, units of degrees.
  - PSI_KEY
```
public static final ConfigKey<Double> PSI_KEY
```
    Config key for third Euler angle of rotation, units of degrees.
  - ZOOM_KEY
```
public static final ConfigKey<Double> ZOOM_KEY
```
    Config key for zoom factor.
  - XOFF_KEY
```
public static final ConfigKey<Double> XOFF_KEY
```
    Config key for graphics X offset, units of 1/2 screen size.
  - YOFF_KEY
```
public static final ConfigKey<Double> YOFF_KEY
```
    Config key for graphics Y offset, units of 1/2 screen size.
  - ISO_CENTER_TOLERANCE
```
public static final double ISO_CENTER_TOLERANCE
```
    Proportional auto-ranging isotropic snap-to-origin threshold.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - CubeSurfaceFactory
```
public CubeSurfaceFactory(boolean isIso)
```
    Constructs an isotropic or non-isotropic cube surface factory.
    
    Parameters:
    
    isIso - whether to operate in isotropic mode
- Method Detail
  - createSurface
```
public Surface createSurface(Rectangle plotBounds,
                             CubeSurfaceFactory.Profile profile,
                             CubeAspect aspect)
```
    Description copied from interface: SurfaceFactory
    
    Returns a new plot surface.
    
    Specified by:
    
    createSurface in interface SurfaceFactory<CubeSurfaceFactory.Profile,CubeAspect>
    
    Parameters:
    
    plotBounds - rectangle to containing actual plot data (not insets)
    
    profile - configuration object defining plot style
    
    aspect - configuration object defining plot viewpoint
    
    Returns:
    
    new plot surface
  - getProfileKeys
```
public ConfigKey<?>[] getProfileKeys()
```
    Description copied from interface: SurfaceFactory
    
    Returns the configuration keys used to configure profile for this surface factory. The returned keys are used in the map supplied to the createProfile method.
    
    Specified by:
    
    getProfileKeys in interface SurfaceFactory<CubeSurfaceFactory.Profile,CubeAspect>
    
    Returns:
    
    profile configuration keys
  - createProfile
```
public CubeSurfaceFactory.Profile createProfile(ConfigMap config)
```
    Description copied from interface: SurfaceFactory
    
    Creates a profile that can be used when creating a plot surface. The keys that are significant in the supplied config map are those returned by getProfileKeys. The return value can be used as input to createSurface and other methods in this class.
    
    Specified by:
    
    createProfile in interface SurfaceFactory<CubeSurfaceFactory.Profile,CubeAspect>
    
    Parameters:
    
    config - map of profile configuration items
    
    Returns:
    
    factory-specific plot surface profile
  - getAspectKeys
```
public ConfigKey<?>[] getAspectKeys()
```
    Description copied from interface: SurfaceFactory
    
    Returns the configuration keys that may be used to configure aspect for this surface factory. The returned keys are used in the map supplied to the useRanges and createAspect methods.
    
    Specified by:
    
    getAspectKeys in interface SurfaceFactory<CubeSurfaceFactory.Profile,CubeAspect>
    
    Returns:
    
    aspect configuration keys
  - useRanges
```
public boolean useRanges(CubeSurfaceFactory.Profile profile,
                         ConfigMap config)
```
    Description copied from interface: SurfaceFactory
    
    Indicates whether ranges should be provided to generate an aspect. If true, it is beneficial to pass the result of readRanges to createAspect alongside the arguments of this method. If false, any such ranges will be ignored.
    
    Specified by:
    
    useRanges in interface SurfaceFactory<CubeSurfaceFactory.Profile,CubeAspect>
    
    Parameters:
    
    profile - surface configuration profile
    
    config - configuration map that may contain keys from getAspectKeys
    
    Returns:
    
    true iff calculated ranges will be of use
  - createAspect
```
public CubeAspect createAspect(CubeSurfaceFactory.Profile profile,
                               ConfigMap config,
                               Range[] ranges)
```
    Description copied from interface: SurfaceFactory
    
    Creates an aspect from configuration information. The ranges argument will be used only if useRanges returns true. It is legal to give the ranges argument as null in any case. In all cases, the returned value must be non-null and usable by createSurface.
    
    Specified by:
    
    createAspect in interface SurfaceFactory<CubeSurfaceFactory.Profile,CubeAspect>
    
    Parameters:
    
    profile - surface configuration profile
    
    config - configuration map that may contain keys from getAspectKeys
    
    ranges - range data filled in from layers, or null
    
    Returns:
    
    new aspect
  - getAspectConfig
```
public ConfigMap getAspectConfig(Surface surface)
```
    Description copied from interface: SurfaceFactory
    
    Returns a ConfigMap that corresponds to the configuration of the given surface, which must have been created by this factory. The intention is that supplying the returned config items to this object's createAspect method with the right profile should come up with approximately the same surface, preferably without reference to any supplied ranges.
    The returned config items should be optimised for presentation to the user, so that for instance decimal values are reported to a reasonable level of precision. Because of this, and perhaps for other reasons related to implementation, a surface resulting from feeding the returned config back to this factory may not be identical to the supplied surface, so round-tripping is not guaranteed to be exact.
    
    Specified by:
    
    getAspectConfig in interface SurfaceFactory<CubeSurfaceFactory.Profile,CubeAspect>
    
    Parameters:
    
    surface - plot surface; if it was not created by this factory, behaviour is undefined
    
    Returns:
    
    config map populated with items that should approximately reproduce the supplied surface
  - readRanges
```
public Range[] readRanges(CubeSurfaceFactory.Profile profile,
                          PlotLayer[] layers,
                          DataStore dataStore)
```
    Description copied from interface: SurfaceFactory
    
    Provides the ranges that may be passed to createAspect. There is only any point calling this if useRanges returns true.
    
    Specified by:
    
    readRanges in interface SurfaceFactory<CubeSurfaceFactory.Profile,CubeAspect>
    
    Parameters:
    
    profile - surface configuration profile
    
    layers - plot layers to be plotted
    
    dataStore - contains actual data
    
    Returns:
    
    data ranges covered by the given layers filled in from data
  - getNavigatorKeys
```
public ConfigKey<?>[] getNavigatorKeys()
```
    Description copied from interface: SurfaceFactory
    
    Returns the configuration keys that may be used to configure a navigator for use with this surface factory. The returned keys are used in the map supplied to the SurfaceFactory.createNavigator(uk.ac.starlink.ttools.plot2.config.ConfigMap) method.
    
    Specified by:
    
    getNavigatorKeys in interface SurfaceFactory<CubeSurfaceFactory.Profile,CubeAspect>
    
    Returns:
    
    navigator configuration keys
  - createNavigator
```
public Navigator<CubeAspect> createNavigator(ConfigMap navConfig)
```
    Description copied from interface: SurfaceFactory
    
    Creates a navigator from configuration information. The returned value will be non-null.
    
    Specified by:
    
    createNavigator in interface SurfaceFactory<CubeSurfaceFactory.Profile,CubeAspect>
    
    Parameters:
    
    navConfig - configuration map that may contain keys from getNavigatorKeys
    
    Returns:
    
    navigator for use with surfaces produced by this factory
  - getPlotMetric
```
public PlotMetric getPlotMetric()
```
    Returns null.
    
    Specified by:
    
    getPlotMetric in interface SurfaceFactory<CubeSurfaceFactory.Profile,CubeAspect>
    
    Returns:
    
    plot metric, or null
  - getRotation
```
public static double[] getRotation(ConfigMap config)
```
    Reads the intended rotation matrix from a configuration map.
    
    Parameters:
    
    config - config map
    
    Returns:
    
    9-element rotation matrix
  - eulerToRotationDegrees
```
public static double[] eulerToRotationDegrees(double[] eulers)
```
    Converts three ZXZ Euler angles to a rotation matrix.
    
    Parameters:
    
    eulers - 1, 2 or 3-element array giving Euler angles phi, theta, psi in degrees; if fewer elements than 3, later angles are assumed zero
    
    Returns:
    
    9-element rotation matrix
  - rotationToEulerDegrees
```
public static double[] rotationToEulerDegrees(double[] rotmat)
```
    Converts rotation matrix to three ZXZ Euler angles in degrees. May lose some accuracy near theta=0. Note the result is not unique.
    
    Parameters:
    
    rotmat - 9-element rotation matrix
    
    Returns:
    
    3-element array giving phi, theta, psi in degrees

Class CubeSurfaceFactory

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

XLOG_KEY

YLOG_KEY

ZLOG_KEY

XFLIP_KEY

YFLIP_KEY

ZFLIP_KEY

XLABEL_KEY

YLABEL_KEY

ZLABEL_KEY

FRAME_KEY

XCROWD_KEY

YCROWD_KEY

ZCROWD_KEY

ISOCROWD_KEY

XMIN_KEY

XMAX_KEY

XSUBRANGE_KEY

YMIN_KEY

YMAX_KEY

YSUBRANGE_KEY

ZMIN_KEY

ZMAX_KEY

ZSUBRANGE_KEY

XC_KEY

YC_KEY

ZC_KEY

SCALE_KEY

PHI_KEY

THETA_KEY

PSI_KEY

ZOOM_KEY

XOFF_KEY

YOFF_KEY

ISO_CENTER_TOLERANCE

Constructor Detail

CubeSurfaceFactory

Method Detail

createSurface

getProfileKeys

createProfile

getAspectKeys

useRanges

createAspect

getAspectConfig

readRanges

getNavigatorKeys

createNavigator

getPlotMetric

getRotation

eulerToRotationDegrees

rotationToEulerDegrees