# Class Plot3D

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
uk.ac.starlink.ttools.plot.TablePlot
uk.ac.starlink.ttools.plot.Plot3D

All Implemented Interfaces:
  `ImageObserver, MenuContainer, Serializable`

Direct Known Subclasses:
  `CartesianPlot3D, SphericalPlot3D`

public abstract class Plot3D extends TablePlot
Component which paints a 3d plot.

Since:
  22 Nov 2005
Author:
  Mark Taylor
See Also:
  - Serialized Form

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`protected static class`
`Plot3D.RangeChecker`
Interface for checking that a 3-d coordinate is in range.
`protected static class`
`Plot3D.Transformer3D`
Transforms points in 3d data space to points in 3d graphics space.

### Nested classes/interfaces inherited from class JComponent

`JComponent.AccessibleJComponent`

### Nested classes/interfaces inherited from class Container

`Container.AccessibleAWTContainer`

### Nested classes/interfaces inherited from class Component

`Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy`

## Field Summary

Fields
Modifier and Type
Field
Description
`protected double[]`
`hiBounds_`
`protected double[]`
`hiBoundsG_`
`protected double[]`
`loBounds_`
`protected double[]`
`loBoundsG_`

### Fields inherited from class JComponent

`listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW`

### Fields inherited from class Component

`accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT`

### Fields inherited from interface ImageObserver

`ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH`

## Constructor Summary

Constructors
Constructor
Description
`Plot3D()`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`protected abstract Plot3D.RangeChecker`
`configureRanges(Plot3DState state)`
Provides notification that the range constraints are now as described in a supplied `state` object.
`protected abstract boolean`
`frontOnly(Plot3DState state)`
Indicates whether only the front part of the plot should be plotted.
`protected abstract boolean[]`
`get3DLogFlags()`
Returns an array of 3 flags which indicate whether logarithmic scaling is in force on the X, Y and Z axes respectively.
`Rectangle`
`getDisplayBounds()`
Returns the bounds of the apparent display area.
`protected abstract double`
`getPadding(Plot3DState state, Graphics g, int[] padBorders)`
Works out padding factors to be used for the plot volume.
`Rectangle`
`getPlotBounds()`
Returns the bounds of the actual plotting area.
`PointIterator`
`getPlottedPointIterator()`
Returns an iterator over the points plotted last time this component painted itself.
`PointPlacer`
`getPointPlacer()`
Returns a point placer for mapping 3D data points to the screen.
`protected static boolean`
`logize(double[] coords, boolean[] logFlags)`
Converts coordinates to logarithmic values if necessary.
`protected boolean`
`paintMemoryError(OutOfMemoryError e)`
Hook for handling OutOfMemoryErrors which may be generated during plotting.
`protected abstract void`
`plotAxes(Plot3DState state, Graphics g, Plot3D.Transformer3D trans, PlotVolume vol, boolean front)`
Draws grid lines which contain all the known points.
`static double[]`
`rotate(double[] base, double[] screenAxis, double theta)`
Calculates a rotation matrix for rotating around a screen axis by a given angle.
`static double[]`
`rotateXY(double[] base, double phi, double psi)`
Takes a view rotation matrix and adds to it the effect of rotations about X and Y directions.
`void`
`setState(PlotState state)`
Sets the plot state for this plot.
`protected static boolean`
`transformErrors(Plot3D.Transformer3D trans, Plot3D.RangeChecker ranger, boolean[] logFlags, double[][] errors, double[] xerrs, double[] yerrs, double[] zerrs)`
Transforms errors from the form they assume in input data (offsets to a central data point in data space) to a set of absolute coordinates of points in the transformed graphics space.

### Methods inherited from class TablePlot

`addPlotListener, calculateBounds, firePlotChangedLater, getState, isVectorContext, removePlotListener`

### Methods inherited from class JComponent

`addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUI, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI`

### Methods inherited from class Container

`add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree`

### Methods inherited from class Component

`action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAccessibleContext, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMixingCutoutShape, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle`

### Methods inherited from class Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Field Details

### loBounds_

protected double[] loBounds_

### hiBounds_

protected double[] hiBounds_

### loBoundsG_

protected double[] loBoundsG_

### hiBoundsG_

protected double[] hiBoundsG_

## Constructor Details

### Plot3D

public Plot3D()
Constructor.

## Method Details

### configureRanges

protected abstract Plot3D.RangeChecker configureRanges(Plot3DState state)
Provides notification that the range constraints are now as described in a supplied `state` object. A suitable `Plot3D.RangeChecker` object should be returned, but the implementation should take care of any other updates to its internal state which are required as well.

Parameters:
  `state` - plot state
Returns:
  a range checker appropriate to `state`'s range constraints

### getPadding

protected abstract double getPadding(Plot3DState state, Graphics g, int[] padBorders)
Works out padding factors to be used for the plot volume. The return value is the `padFactor`; the amount of space outside the unit cube in both dimensions. 1 means no extra space. The `padBorders` array is a 4-element array whose values on entry are ignored; on exit it should contain space, additional to `padFactor`, to be left around the edges of the plot. The order is (left,right,bottom,top).

Parameters:
  `state` - plot state
  `g` - graphics context
  `padBorders` - 4-element array, filled on return
Returns:
  pad factor (>=1)
See Also:
  - `PlotVolume(Component, Graphics, MarkStyle[], double, int[], double)`

### frontOnly

protected abstract boolean frontOnly(Plot3DState state)
Indicates whether only the front part of the plot should be plotted.

Parameters:
  `state` - plot state
Returns:
  true iff parts of the plot behind the centre of the Z axis should be ignored

### get3DLogFlags

protected abstract boolean[] get3DLogFlags()
Returns an array of 3 flags which indicate whether logarithmic scaling is in force on the X, Y and Z axes respectively.

Returns:
  3-element array of Cartesian axis log scaling flags

### plotAxes

protected abstract void plotAxes(Plot3DState state, Graphics g, Plot3D.Transformer3D trans, PlotVolume vol, boolean front)
Draws grid lines which contain all the known points. According to the value of the `front` parameter, either the lines which are behind all the data points, or the lines which are in front of all the data points are drawn. Thus, the routine needs to be called twice to plot all the lines. The graphics context has had all the customisation it needs.

Parameters:
  `state` - plot state
  `g` - graphics context
  `trans` - transformer which maps data space to 3d graphics space
  `vol` - the plotting volume onto which the plot is done
  `front` - true for lines in front of data, false for lines behind

### setState

public void setState(PlotState state)
Description copied from class: `TablePlot`
Sets the plot state for this plot. This characterises how the plot will be done next time this component is painted.

Overrides:
  `setState` in class `TablePlot`
Parameters:
  `state` - plot state

### getPlotBounds

public Rectangle getPlotBounds()
Returns the bounds of the actual plotting area.

Specified by:
  `getPlotBounds` in class `TablePlot`
Returns:
  plot area bounds

### getDisplayBounds

public Rectangle getDisplayBounds()
Returns the bounds of the apparent display area. This is the actual plotting area with some padding.

Returns:
  display area bounds

### getPlottedPointIterator

public PointIterator getPlottedPointIterator()
Returns an iterator over the points plotted last time this component painted itself.

Returns:
  point iterator

### getPointPlacer

public PointPlacer getPointPlacer()
Returns a point placer for mapping 3D data points to the screen.

Returns:
  point placer

### logize

protected static boolean logize(double[] coords, boolean[] logFlags)
Converts coordinates to logarithmic values if necessary. The `coords` array holds the input values on entry, and each of these will be turned into logarithms of themselves on exit iff the corresponding element of the logFlags array is true. The return value will be true if the conversion went OK, and false if it couldn't be done for at least one coordinate, because it was non-positive.

Parameters:
  `coords` - 3-element coordinate array

### transformErrors

protected static boolean transformErrors(Plot3D.Transformer3D trans, Plot3D.RangeChecker ranger, boolean[] logFlags, double[][] errors, double[] xerrs, double[] yerrs, double[] zerrs)
Transforms errors from the form they assume in input data (offsets to a central data point in data space) to a set of absolute coordinates of points in the transformed graphics space. The arrangement of the input data offsets (`loErrs`, `hiErrs`) is as determined by the `PlotData` object. The number and ordering of the output data points (`xerrs`, `yerrs`, `zerrs`) are as required by `ErrorRenderer` objects.

Points which don't represent errors, either because they have zero offsets or because they fall outside of the range of this 3D plot, are represented in the output coordinates as `Double.NaN`. The return value indicates whether any of the transformed values have non-blank values - if false, then error drawing is pointless.

Parameters:
  `trans` - data space -> graphics space transformer
  `ranger` - range checker - anything out of range will be discarded
  `logFlags` - flags for which axes will be plotted logarithmically
  `errors` - data space error points, in pairs
  `xerrs` - graphics space X coordinates for error points
  `yerrs` - graphics space Y coordinates for error points
  `zerrs` - graphics space Z coordinates for error points
Returns:
  true if some of the calculated errors are non-blank

### rotateXY

public static double[] rotateXY(double[] base, double phi, double psi)
Takes a view rotation matrix and adds to it the effect of rotations about X and Y directions.

Parameters:
  `base` - 9-element array giving initial view rotation matrix
  `phi` - angle to rotate around Y axis
  `psi` - angle to rotate around X axis
Returns:
  9-element array giving combined rotation matrix

### rotate

public static double[] rotate(double[] base, double[] screenAxis, double theta)
Calculates a rotation matrix for rotating around a screen axis by a given angle. Note this axis is in the view space, not the data space.

Parameters:
  `base` - rotation matrix defining the view orientation (9-element array)
  `screenAxis` - axis in view space about which rotation is required (3-element array)
  `theta` - rotation angle in radians

### paintMemoryError

protected boolean paintMemoryError(OutOfMemoryError e)
Hook for handling OutOfMemoryErrors which may be generated during plotting. May be called from the event dispatch thread. The Plot3D implementation returns false.

Parameters:
  `e` - error
Returns:
  true iff the error is handled (for intance user is informed)