## visad
Class ScalarMap

    java.lang.Object
      visad.ScalarMap

All Implemented Interfaces:
  Cloneable, Comparable, Serializable

Direct Known Subclasses:
  ConstantMap

public class ScalarMap
extends Object
implements Cloneable, Serializable, Comparable

A ScalarMap object defines a mapping from a RealType to a DisplayRealType. A set of ScalarMap objects define how data are dislayed.

The mapping of values is linear. Any non-linear mapping must be handled by Display CoordinateSystem-s.

See Also:
  Serialized Form

Field Summary
`(package private) double[]` `displayRange` ranges of values of DisplayScalar
`(package private) boolean` `isScaled` true if Scalar values need to be scaled
`(package private) int` `ValueIndex`

Constructor Summary
`` `ScalarMap(ScalarType scalar, DisplayRealType display_scalar)` Construct a `ScalarMap` that maps the scalar to the display_scalar.
`(package private)` `ScalarMap(ScalarType scalar, DisplayRealType display_scalar, boolean needNonNullScalar)`

Method Summary
`void` `addScalarMapListener(ScalarMapListener listener)` add a ScalarMapListener, to be notified whenever setRange is invoked
`boolean` `badRange()`
`boolean` `checkTicks(DataRenderer r, DataDisplayLink link)` return true if application called setRange
`Object` `clone()` Create and return a copy of this ScalarMap.
`int` `compareTo(Object o)` Compares this ScalarMap with another object.
`protected int` `compareTo(ScalarMap that)` Compares this ScalarMap with another ScalarMap.
`protected void` `copy(ScalarMap map)`
`boolean` `doInitialize()`
`static void` `equalizeFlow(Vector mapVector, DisplayTupleType flow_tuple)` ensure that non-Manual components of flow_tuple have equal dataRanges symmetric about 0.0
`boolean` `equals(Object o)` Indicates if this ScalarMap is the same as another object.
`AxisScale` `getAxisScale()` Get the AxisScale associated with this ScalarMap.
`Control` `getControl()` Gets the Control for the DisplayScalar.
`DisplayImpl` `getDisplay()` Get the DisplayImpl this ScalarMap is linked to
`DisplayRealType` `getDisplayScalar()` Get the DisplayRealType that is the map range
`(package private) int` `getDisplayScalarIndex()` Get index of DisplayScalar in display.DisplayRealTypeVector
`Unit` `getOverrideUnit()` Return the override unit.
`double[]` `getRange()` Returns the current range of the `RealType` data.
`ScalarType` `getScalar()` Get the ScalarType that is the map domain
`(package private) int` `getScalarIndex()` get index of Scalar in display.RealTypeVector
`String` `getScalarName()` Get the name being used on the axis scale.

`boolean`

`getScale(double[] so, double[] data, double[] display)`
return value is true if data (RealType) values are linearly scaled to display (DisplayRealType) values; if so, then values are scaled by: display_value = data_value * so[0] + so[1]; (data[0], data[1]) defines range of data values (either passed in to setRange or computed by autoscaling logic) and (display[0], display[1]) defines range of display values; so, data, display must each be passed in as double[2] arrays; note if overrideUnit != null, so and data are in overrideUnit

`boolean` `getScaleEnable()` See if the AxisScale is visible or not.
`int` `getValueIndex()` get index of DisplayScalar in value array used by ShadowType.doTransform
`int` `hashCode()` Returns the hash code for this ScalarMap.
`long` `incTick()` invoke incTick on every application call to setRange
`float[]` `inverseScaleValues(float[] values)` return an array of data (RealType) values by inverse linear scaling (if applicable) the display_values array (DisplayRealType values); this is useful for direct manipulation and cursor labels
`float[]` `inverseScaleValues(float[] values, boolean newArray)` return an array of data (RealType) values by inverse linear scaling (if applicable) the display_values array (DisplayRealType values); this is useful for direct manipulation and cursor labels
`boolean` `isAutoScale()` determine whether this ScalarMap is auto-scaled
`void` `makeScale()` Create the scale that is displayed.
`(package private) void` `nullDisplay()` Clear the link to the VisAD display.
`boolean` `peekTicks(DataRenderer r, DataDisplayLink link)`
`void` `removeScalarMapListener(ScalarMapListener listener)` remove a ScalarMapListener
`void` `resetAutoScale()` re-enable auto-scaling for this ScalarMap
`(package private) void` `resetTicks()` reset tickFlag
`byte[]` `scaleValues(byte[] values, int factor)` return an array of display (DisplayRealType) values by linear scaling (if applicable) the data_values array (RealType values); results are scaled by the given scale factor
`float[]` `scaleValues(double[] values)` return an array of display (DisplayRealType) values by linear scaling (if applicable) the data_values array (RealType values)
`float[]` `scaleValues(float[] values)` return an array of display (DisplayRealType) values by linear scaling (if applicable) the data_values array (RealType values)
`float[]` `scaleValues(float[] values, boolean newArray)` return an array of display (DisplayRealType) values by linear scaling (if applicable) the data_values array (RealType values)
`(package private) void` `setAspectCartesian(double[] aspect)` set aspect ratio of XAxis, YAxis & ZAxis in ScalarMaps rather than matrix (i.e., don't distort text fonts); won't work for spherical, polar, cylindrical coordinates
`(package private) void` `setControl()` Creates the Control for the associated DisplayScalar.
`(package private) void` `setDisplay(DisplayImpl d)` Set the DisplayImpl this ScalarMap is linked to
`(package private) void` `setDisplayScalarIndex(int index)` set index of DisplayScalar in display.DisplayRealTypeVector
`void` `setOverrideUnit(Unit unit)` Set display Unit to override default Unit of Scalar; MUST be called before any data are displayed
`void` `setRange(DataShadow shadow)` set range used for linear map from Scalar to DisplayScalar values; this is the call for automatic scaling
`void` `setRange(double low, double hi)` Explicitly sets the range of `RealType` data values that is mapped to the natural range of `DisplayRealType` display values.

`void`

`setRange(double low, double hi, int remoteId)`
explicitly set the range of data (RealType) values; used for linear map from Scalar to DisplayScalar values; if neither this nor setRangeByUnits is invoked, then the range will be computed from the initial values of Data objects linked to the Display by autoscaling logic; if the range of data values is (0.0, 1.0), for example, this method may be invoked with low = 1.0 and hi = 0.0 to invert the display scale .

`void` `setRangeByUnits()` explicitly set the range of data (RealType) values according to Unit conversion between this ScalarMap's RealType and DisplayRealType (both must have Units and they must be convertable; if neither this nor setRange is invoked, then the range will be computed from the initial values of Data objects linked to the Display by autoscaling logic.
`(package private) void` `setScalarIndex(int index)` set index of Scalar in display.RealTypeVector
`void` `setScalarName(String name)` Set the name being used on the axis scale.
`void` `setScaleColor(float[] color)` Set color of axis scales; color must be float[3] with red, green and blue components; DisplayScalar must be XAxis, YAxis or ZAxis.
`void` `setScaleEnable(boolean on)` Enable the display of the scale for this map.
`void` `setTicks()` set tickFlag according to OldTick and NewTick
`void` `setUnderscoreToBlank(boolean u2b)` Change underscore characters (_) in the Scalar name to blanks.
`void` `setValueIndex(int index)` set index of DisplayScalar in value array used by ShadowType.doTransform
`String` `toString()` Returns a string representation of the ScalarMap.
`String` `toString(String pre)` Returns a string representation of the ScalarMap with the specified prefix prepended.

Methods inherited from class java.lang.Object
`finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### ValueIndex

    int ValueIndex

### isScaled

    boolean isScaled

  true if Scalar values need to be scaled

### displayRange

    double[] displayRange

  ranges of values of DisplayScalar

Constructor Detail

### ScalarMap

    public ScalarMap(ScalarType scalar,
                     DisplayRealType display_scalar)
              throws VisADException

  Construct a `ScalarMap` that maps the scalar to the display_scalar.

Parameters:
  `scalar` - ScalarType (must be RealType at present)
  `display_scalar` - DisplayScalar to map to. If the display_scalar is one of the spatial axes (X, Y, Z) an AxisScale will be created.
Throws:
  `VisADException` - VisAD error

### ScalarMap

    ScalarMap(ScalarType scalar,
              DisplayRealType display_scalar,
              boolean needNonNullScalar)
        throws VisADException

Method Detail

### resetAutoScale

    public void resetAutoScale()

  re-enable auto-scaling for this ScalarMap

### isAutoScale

    public boolean isAutoScale()

  determine whether this ScalarMap is auto-scaled

### doInitialize

    public boolean doInitialize()

### setOverrideUnit

    public void setOverrideUnit(Unit unit)
                         throws VisADException

  Set display Unit to override default Unit of Scalar; MUST be called before any data are displayed

  Parameters:
    `unit` - unit that data will be displayed with
  Throws:
    `VisADException` - `unit` is not convertable with the default unit or scalar is not a RealType.

### getOverrideUnit

    public Unit getOverrideUnit()

  Return the override unit.

  Returns:
    Unit being used in the display.

### getScalarName

    public String getScalarName()

  Get the name being used on the axis scale.

  Returns:
    name of the scale - either the default or the one set by `setScalarName`
  See Also:
    `setScalarName(String name)`

### setScalarName

    public void setScalarName(String name)

  Set the name being used on the axis scale.

  See Also:
    `AxisScale.setTitle(String name)`

### incTick

    public long incTick()

  invoke incTick on every application call to setRange

### setTicks

    public void setTicks()

  set tickFlag according to OldTick and NewTick

### peekTicks

    public boolean peekTicks(DataRenderer r,
                             DataDisplayLink link)

### checkTicks

    public boolean checkTicks(DataRenderer r,
                              DataDisplayLink link)

  return true if application called setRange

### resetTicks

    void resetTicks()

  reset tickFlag

### getScalar

    public ScalarType getScalar()

  Get the ScalarType that is the map domain

  Returns:
    ScalarType of map domain

### getDisplayScalar

    public DisplayRealType getDisplayScalar()

  Get the DisplayRealType that is the map range

  Returns:
    DisplayRealType of map range

### getDisplay

    public DisplayImpl getDisplay()

  Get the DisplayImpl this ScalarMap is linked to

  Returns:
    display that this ScalarMap is linked to

### nullDisplay

    void nullDisplay()
               throws RemoteException,
                      VisADException

  Clear the link to the VisAD display. This will subsequently cause `getDisplay()` and `getControl()` to return `null`; consequently, information stored in the Control might have to be reestablished. This method invokes the method `ScalarMapListener.controlChanged(ScalarMapControlEvent)` on all registered `ScalarMapListener`s with this instance as the event source, `ScalarMapEvent.CONTROL_REMOVED` as the event ID, and the control as the event control.

  Throws:
    `RemoteException` - Java RMI failure
    `VisADException` - VisAD failure

### setDisplay

    void setDisplay(DisplayImpl d)
              throws VisADException

  Set the DisplayImpl this ScalarMap is linked to

  Parameters:
    `d` - display to link to
  Throws:
    `VisADException` - map is already linked to a DisplayImpl or other VisAD error

### getControl

    public Control getControl()

  Gets the Control for the DisplayScalar. The Control is constructed when this ScalarMap is linked to a Display via an invocation of the `Display.addMap(ScalarMap)` method. Not all ScalarMaps have Controls, generally depending on the ScalarMap's DisplayRealType. If a ScalarMap is removed from a Display (via the `Display.clearMaps()` method, then, in general, any information in the ScalarMap's control will be lost and must be reestablished.

  Returns:
    The Control for the DisplayScalar or `null` if one has not yet been set.

### setControl

    void setControl()
              throws VisADException,
                     RemoteException

  Creates the Control for the associated DisplayScalar. This method invokes the method `ScalarMapListener.controlChanged(ScalarMapControlEvent)` on all registered `ScalarMapListener`s with this instance as the event source and `ScalarMapEvent.CONTROL_ADDED` or `ScalarMapEvent.CONTROL_REPLACED` as the event ID -- depending on whether this is the first control or not. The event control is the previous control if the event ID is `ScalarMapEvent.CONTROL_REPLACED`. If the event ID is `ScalarMapEvent.CONTROL_ADDED`, then the event control is the created control or `null` -- depending on whether or not the control was successfully created.

  Throws:
    `RemoteException` - Java RMI failure
    `VisADException` - VisAD failure

### getScale

    public boolean getScale(double[] so,
                            double[] data,
                            double[] display)

  return value is true if data (RealType) values are linearly scaled to display (DisplayRealType) values; if so, then values are scaled by: display_value = data_value * so[0] + so[1]; (data[0], data[1]) defines range of data values (either passed in to setRange or computed by autoscaling logic) and (display[0], display[1]) defines range of display values; so, data, display must each be passed in as double[2] arrays; note if overrideUnit != null, so and data are in overrideUnit

  Parameters:
    `so` - array to contain scale and offset
    `data` - array to contain the data range
    `display` - array to contain the display range
  Returns:
    true if data are linearly scaled

### getRange

    public double[] getRange()

  Returns the current range of the `RealType` data. The range is implicitly set by autoscaling logic or may be explicitly set by the `setRange(double,double)` method. Note that if overrideUnit != null, then dataRange is in overrideUnit.

  Returns:
    The current range of the `RealType` data. The array is new and may be safely modified.

### setRangeByUnits

    public void setRangeByUnits()
                         throws VisADException,
                                RemoteException

  explicitly set the range of data (RealType) values according to Unit conversion between this ScalarMap's RealType and DisplayRealType (both must have Units and they must be convertable; if neither this nor setRange is invoked, then the range will be computed from the initial values of Data objects linked to the Display by autoscaling logic.

  Throws:
    `VisADException` - VisAD error
    `RemoteException` - Java RMI error

### setRange

    public void setRange(double low,
                         double hi)
                  throws VisADException,
                         RemoteException

  Explicitly sets the range of `RealType` data values that is mapped to the natural range of `DisplayRealType` display values. This method is used to define a linear map from Scalar to DisplayScalar values. If neither this nor `setRangeByUnits()` is invoked, then the range will be computed by autoscaling logic from the initial values of Data objects linked to the Display. If the range of data values is (0.0, 1.0), for example, this method may be invoked with low = 1.0 and hi = 0.0 to invert the display scale.

  Parameters:
    `low` - One end of the range of applicable data.
    `hi` - The other end of the range of applicable data.
  Throws:
    `VisADException` - VisAD failure.
    `RemoteException` - Java RMI failure.

### setRange

    public void setRange(double low,
                         double hi,
                         int remoteId)
                  throws VisADException,
                         RemoteException

  explicitly set the range of data (RealType) values; used for linear map from Scalar to DisplayScalar values; if neither this nor setRangeByUnits is invoked, then the range will be computed from the initial values of Data objects linked to the Display by autoscaling logic; if the range of data values is (0.0, 1.0), for example, this method may be invoked with low = 1.0 and hi = 0.0 to invert the display scale .

  Parameters:
    `low` - lower range value (see notes above)
    `hi` - upper range value (see notes above)
  Throws:
    `VisADException` - VisAD error
    `RemoteException` - Java RMI error

### setRange

    public void setRange(DataShadow shadow)
                  throws VisADException,
                         RemoteException

  set range used for linear map from Scalar to DisplayScalar values; this is the call for automatic scaling

  Throws:
    `VisADException`
    `RemoteException`

### addScalarMapListener

    public void addScalarMapListener(ScalarMapListener listener)

  add a ScalarMapListener, to be notified whenever setRange is invoked

  Parameters:
    `listener` - `ScalarMapListener` to recieve notification of changes.

### removeScalarMapListener

    public void removeScalarMapListener(ScalarMapListener listener)

  remove a ScalarMapListener

  Parameters:
    `listener` - `ScalarMapListener` to remove from the list

### setUnderscoreToBlank

    public void setUnderscoreToBlank(boolean u2b)

  Change underscore characters (_) in the Scalar name to blanks. Can be used to change the displayed scalar name on the axis.

  Parameters:
    `u2b` - true to change, false to change back
  See Also:
    `as an alternative`

### makeScale

    public void makeScale()
                   throws VisADException

  Create the scale that is displayed. This is called automatically when `setRange(lo, hi)` and `setDisplay` are called. It makes a call to `AxisScale.makeScale()` where the actual hard work is done.

  Throws:
    `VisADException` - VisAD error.

### setScaleEnable

    public void setScaleEnable(boolean on)

  Enable the display of the scale for this map. This can be used to selectively turn on or off the scales in a display. Must be used in conjunction with `GraphicsModeControl.setScaleEnable()` or `DisplayRenderer.setScaleOn(boolean on)`.

  Parameters:
    `on` - true will enable display of axis, false will disable display
  See Also:
    `GraphicsModeControl.setScaleEnable(boolean enable)`, `DisplayRenderer.setScaleOn(boolean on)`, `AxisScale.setVisible(boolean visible)`

### getScaleEnable

    public boolean getScaleEnable()

  See if the AxisScale is visible or not.

  Returns:
    true if the AxisScale is visible

### setScaleColor

    public void setScaleColor(float[] color)
                       throws VisADException

  Set color of axis scales; color must be float[3] with red, green and blue components; DisplayScalar must be XAxis, YAxis or ZAxis. Preferred method is to use `AxisScale.setColor`methods.

  ``
  Parameters:
    `color` - array of R,G,B values of color.
  Throws:
    `VisADException` - non-spatial DisplayScalar or wrong length of color array
  See Also:
    `getAxisScale()`, `AxisScale.setColor(Color color)`, `AxisScale.setColor(float[] color)`

### badRange

    public boolean badRange()

### scaleValues

    public float[] scaleValues(double[] values)

  return an array of display (DisplayRealType) values by linear scaling (if applicable) the data_values array (RealType values)

  Parameters:
    `values` - to scale as doubles
  Returns:
    array of display values

### scaleValues

    public float[] scaleValues(float[] values)

  return an array of display (DisplayRealType) values by linear scaling (if applicable) the data_values array (RealType values)

  Parameters:
    `values` - to scale as floats
  Returns:
    array of display values

### scaleValues

    public float[] scaleValues(float[] values,
                               boolean newArray)

  return an array of display (DisplayRealType) values by linear scaling (if applicable) the data_values array (RealType values)

  Parameters:
    `values` - to scale as floats
    `newArray` - false to scale in place
  Returns:
    array of display values

### scaleValues

    public byte[] scaleValues(byte[] values,
                              int factor)
                       throws VisADException

  return an array of display (DisplayRealType) values by linear scaling (if applicable) the data_values array (RealType values); results are scaled by the given scale factor

  Parameters:
    `values` - to scale as bytes
  Returns:
    array of display values
  Throws:
    `VisADException`

### inverseScaleValues

    public float[] inverseScaleValues(float[] values)

  return an array of data (RealType) values by inverse linear scaling (if applicable) the display_values array (DisplayRealType values); this is useful for direct manipulation and cursor labels

  Returns:
    data values

### inverseScaleValues

    public float[] inverseScaleValues(float[] values,
                                      boolean newArray)

  return an array of data (RealType) values by inverse linear scaling (if applicable) the display_values array (DisplayRealType values); this is useful for direct manipulation and cursor labels

  Parameters:
    `newArray` - false to transform in place
  Returns:
    data values

### equalizeFlow

    public static void equalizeFlow(Vector mapVector,
                                    DisplayTupleType flow_tuple)
                             throws VisADException,
                                    RemoteException

  ensure that non-Manual components of flow_tuple have equal dataRanges symmetric about 0.0

  Throws:
    `VisADException`
    `RemoteException`

### getDisplayScalarIndex

    int getDisplayScalarIndex()

  Get index of DisplayScalar in display.DisplayRealTypeVector

### getScalarIndex

    int getScalarIndex()

  get index of Scalar in display.RealTypeVector

### setScalarIndex

    void setScalarIndex(int index)

  set index of Scalar in display.RealTypeVector

### setDisplayScalarIndex

    void setDisplayScalarIndex(int index)

  set index of DisplayScalar in display.DisplayRealTypeVector

### setValueIndex

    public void setValueIndex(int index)

  set index of DisplayScalar in value array used by ShadowType.doTransform

### getValueIndex

    public int getValueIndex()

  get index of DisplayScalar in value array used by ShadowType.doTransform

### compareTo

    public int compareTo(Object o)

  Compares this ScalarMap with another object.

  Specified by:
    `compareTo` in interface `Comparable`
  Parameters:
    `o` - The other object.
  Returns:
    A value that is negative, zero, or positive depending on whether this instance is less than, equal to, or greater than the other object, respectively.
  Throws:
    `ClassCastException` - if the other object isn't a `ScalarMap`.
    `NullPointerException` - if the other object is `null`.

### compareTo

    protected int compareTo(ScalarMap that)

  Compares this ScalarMap with another ScalarMap. The ScalarType-s are first compared; if they compare equal, then the DisplayRealType-s are compared.

  Parameters:
    `that` - The other ScalarMap.
  Returns:
    A value that is negative, zero, or positive depending on whether this ScalarMap is considered less than, equal to, or greater than the other ScalarMap, respectively.

### equals

    public boolean equals(Object o)

  Indicates if this ScalarMap is the same as another object.

  Parameters:
    `o` - The other object.
  Returns:
    `true` if and only if the other object is a ScalarMap and compares equal to this ScalarMap.

### hashCode

    public int hashCode()

  Returns the hash code for this ScalarMap. If `scalarMap1.equals( scalarMap2)` is true, then `scalarMap1.hashCode() == scalarMap2.hashCode()`.

  Returns:
    The hash code for this ScalarMap.

### clone

    public Object clone()

  Create and return a copy of this ScalarMap.

  Returns:
    copy of the ScalarMap or `null` if a copy couldn't be created.

### copy

    protected void copy(ScalarMap map)
                 throws VisADException,
                        RemoteException

  Throws:
    `VisADException`
    `RemoteException`

### toString

    public String toString()

  Returns a string representation of the ScalarMap.

  Returns:
    a string that "textually represents" this ScalarMap.

### toString

    public String toString(String pre)

  Returns a string representation of the ScalarMap with the specified prefix prepended.

  Parameters:
    `pre` - prefix to prepend to the representation
  Returns:
    a string that "textually represents" this ScalarMap with `pre` prepended.

### getAxisScale

    public AxisScale getAxisScale()

  Get the AxisScale associated with this ScalarMap.

  Returns:
    the AxisScale or null if not a spatial ScalarMap

### setAspectCartesian

    void setAspectCartesian(double[] aspect)
                      throws VisADException,
                             RemoteException

  set aspect ratio of XAxis, YAxis & ZAxis in ScalarMaps rather than matrix (i.e., don't distort text fonts); won't work for spherical, polar, cylindrical coordinates

  Parameters:
    `aspect` - ratios; 3 elements for Java3D, 2 for Java2D
  Throws:
    `VisADException` - a VisAD error occurred
    `RemoteException` - an RMI error occurred