# Interface SurfaceFactory<P,A>

All Known Implementing Classes:
  `CubeSurfaceFactory, PlaneSurfaceFactory, SkySurfaceFactory, TimeSurfaceFactory`

public interface SurfaceFactory<P,A>
Generates members of a family of Surface objects. Surface configuration is provided by two objects of parameterised types, a Profile (type P) and an Aspect (type A). The profile provides fixed configuration items, and the aspect provides items that may change according to different views of the same surface, in particular as the result of pan/zoom type operations. This object is self-documenting, in that it can report the the configuration keys required to specify profile/aspect.

Since:
  11 Feb 2013
Author:
  Mark Taylor

## Method Summary

Modifier and Type
Method
Description
`A`
`createAspect(P profile, ConfigMap aspectConfig, Range[] ranges)`
Creates an aspect from configuration information.
`Navigator<A>`
`createNavigator(ConfigMap navigatorConfig)`
Creates a navigator from configuration information.
`P`
`createProfile(ConfigMap config)`
Creates a profile that can be used when creating a plot surface.
`Surface`
`createSurface(Rectangle plotBounds, P profile, A aspect)`
Returns a new plot surface.
`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 an object that can assess distances between graphic positions on the plot surface.
`ConfigKey<?>[]`
`getProfileKeys()`
Returns the configuration keys used to configure profile for this surface factory.
`Range[]`
`readRanges(P profile, PlotLayer[] layers, DataStore dataStore)`
Provides the ranges that may be passed to `createAspect`.
`boolean`
`useRanges(P profile, ConfigMap aspectConfig)`
Indicates whether ranges should be provided to generate an aspect.

## Method Details

### createSurface

Surface createSurface(Rectangle plotBounds, P profile, A aspect)
Returns a new plot surface.

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

ConfigKey<?>[] getProfileKeys()
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.

Returns:
  profile configuration keys

### createProfile

P createProfile(ConfigMap config)
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.

Parameters:
  `config` - map of profile configuration items
Returns:
  factory-specific plot surface profile

### getAspectKeys

ConfigKey<?>[] getAspectKeys()
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.

Returns:
  aspect configuration keys

### useRanges

boolean useRanges(P profile, ConfigMap aspectConfig)
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.

Parameters:
  `profile` - surface configuration profile
  `aspectConfig` - configuration map that may contain keys from `getAspectKeys`
Returns:
  true iff calculated ranges will be of use

### readRanges

@Slow Range[] readRanges(P profile, PlotLayer[] layers, DataStore dataStore)
Provides the ranges that may be passed to `createAspect`. There is only any point calling this if `useRanges` returns true.

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

### createAspect

A createAspect(P profile, ConfigMap aspectConfig, Range[] ranges)
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`.

Parameters:
  `profile` - surface configuration profile
  `aspectConfig` - configuration map that may contain keys from `getAspectKeys`
  `ranges` - range data filled in from layers, or null
Returns:
  new aspect

### getAspectConfig

ConfigMap getAspectConfig(Surface surface)
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.

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

### getNavigatorKeys

ConfigKey<?>[] getNavigatorKeys()
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 `createNavigator(ConfigMap)` method.

Returns:
  navigator configuration keys

### createNavigator

Navigator<A> createNavigator(ConfigMap navigatorConfig)
Creates a navigator from configuration information. The returned value will be non-null.

Parameters:
  `navigatorConfig` - configuration map that may contain keys from `getNavigatorKeys`
Returns:
  navigator for use with surfaces produced by this factory

### getPlotMetric

PlotMetric getPlotMetric()
Returns an object that can assess distances between graphic positions on the plot surface. If no such metric exists, null may be returned.

Returns:
  plot metric, or null