## visad.util
Class DataUtility

    java.lang.Object
      visad.util.DataUtility

public class DataUtility
extends Object

A general utility class for VisAD Data objects

Nested Class Summary
`static class` `DataUtility.RealTupleComparator` Provides support for comparing RealTuple-s of the same RealTupleType.

Constructor Summary
`DataUtility()`

Method Summary
`static Field` `consolidate(Field[] fields)` Consolidates fields.
`static String` `convertMapsToString(ScalarMap[] sm)` Converts the given array of mappings to an easy-to-read String form.
`static String` `convertMapsToString(Vector v)` Converts the given vector of mappings to an easy-to-read String form.
`static ScalarMap[]` `convertStringToMaps(String mapString, Data[] data, boolean showErrors)` Converts the given map string to its corresponding array of mappings.
`static ScalarMap[]` `convertStringToMaps(String mapString, Data data, boolean showErrors)` Converts the given map string to its corresponding array of mappings.
`static ScalarMap[]` `convertStringToMaps(String mapString, Vector types, boolean showErrors)` Converts the given map string to its corresponding array of mappings.
`static GriddedSet` `createGriddedSet(FlatField field, boolean copy)` Creates a GriddedSet from a FlatField.
`static Field` `ensureRange(Field field, MathType newRangeType)` Ensures that the range of a Field is a given type.
`static RealTupleType` `ensureRealTupleType(MathType type)` Ensures that a MathType is a RealTupleType.
`static TupleIface` `ensureTuple(Data datum)` Ensures that a Data is a Tuple.
`static TupleType` `ensureTupleType(MathType type)` Ensures that a MathType is a TupleType.
`static Image` `extractImage(FlatField field, boolean reverse)` Converts a flat field of the form `((x, y) -> (r, g, b))` to an AWT Image.
`static int` `getComponentIndex(Function function, MathType componentType)` Gets the index of a component in the range of a Function.
`static int` `getComponentIndex(Set set, MathType componentType)` Gets the index of a component in a Set.
`static int` `getComponentIndex(TupleType tupleType, MathType componentType)` Gets the index of a component in a TupleType.
`static RealTupleType` `getDomainType(Function function)` Gets the MathType of the domain of a Function.
`static RealTupleType` `getDomainType(Set set)` Gets the MathType of the domain of a Set.
`static RealTupleType` `getFlatRangeType(Function function)` Gets the MathType of the flat-range of a Function.
`static FlatField[]` `getImageFields(Data data)`
`static float[][]` `getPixels(FlatField image)`
`static int` `getRangeDimension(Function function)` Gets the number of components in the range of a Function.
`static TupleType` `getRangeTupleType(Function function)` Gets the TupleType of the range of a Function.
`static MathType` `getRangeType(Function function)` Gets the MathType of the range of a Function.
`static Unit[]` `getRangeUnits(FlatField field)` Gets the units of the (flat) components of the range of a FlatField.
`static int` `getRealTypes(Data[] data, Vector v, boolean keepDupl, boolean doCoordSys)` Deprecated. Use getScalarTypes(Data[], Vector, boolean, boolean) instead.
`static int` `getRealTypes(Data data, Vector v)` Deprecated. Use getScalarTypes(Data, Vector) instead.
`static RealTuple` `getSample(Set set, int index)` Gets the specified sample of a VisAD Set.
`static int` `getScalarTypes(Data[] data, Vector v, boolean keepDupl, boolean doCoordSys)` Obtains a Vector consisting of all ScalarTypes present in an array of Data objects' MathTypes.
`static int` `getScalarTypes(Data data, Vector v)` Obtains a Vector consisting of all ScalarTypes present in a Data object's MathType.
`static ScalarMap[]` `guessMaps(MathType[] types, boolean allow3d)` Attempts to guess a good set of mappings for a display containing Data objects of the given types.
`static boolean` `isSerializable(Object obj)` Verify that an object is Serializable by attempting to serialize it.
`static boolean` `isSerializable(Object obj, boolean printStackTraces)` Verify that an object is Serializable by attempting to serialize it.
`static void` `main(String[] argv)`
`static FlatField` `makeField(Image image)` Create a VisAD Data object from the given Image
`static FlatField` `makeField(Image image, boolean withAlpha)` Create a VisAD Data object from the given Image
`static FlatField` `makeImage(float[][] values)` return a FlatField for a simple image from values[nlines][nelements]
`static DataImpl` `makeLocal(Data data)` Converts a remote Data object to a local Data object.
`static DataImpl` `makeLocal(Data data, boolean printStackTraces)` Converts a remote Data object to a local Data object.
`static DisplayImpl` `makeSimpleDisplay(DataImpl data)`
`static void` `setPixels(FlatField image, float[][] values)` set pixel values in a simple image, indexed as values[line][element]
`static MathType` `simplify(MathType type)` Simplifies a MathType.
`static Tuple` `stringsToTuple(String[] s)` Converts an array of strings into a VisAD Tuple.
`static Tuple` `stringsToTuple(String[] s, boolean printStackTraces)` Converts an array of strings into a VisAD Tuple.
`static String[]` `tupleToStrings(Tuple t)` Converts a VisAD tuple into an array of strings.
`static String[]` `tupleToStrings(Tuple t, boolean printStackTraces)` Converts a VisAD tuple into an array of strings.

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

Constructor Detail

### DataUtility

    public DataUtility()

Method Detail

### makeImage

    public static FlatField makeImage(float[][] values)
                               throws VisADException,
                                      RemoteException

  return a FlatField for a simple image from values[nlines][nelements]

  Throws:
    `VisADException`
    `RemoteException`

### setPixels

    public static void setPixels(FlatField image,
                                 float[][] values)
                          throws VisADException,
                                 RemoteException

  set pixel values in a simple image, indexed as values[line][element]

  Throws:
    `VisADException`
    `RemoteException`

### getPixels

    public static float[][] getPixels(FlatField image)
                               throws VisADException,
                                      RemoteException

  Throws:
    `VisADException`
    `RemoteException`

### makeField

    public static FlatField makeField(Image image)
                               throws IOException,
                                      VisADException

  Create a VisAD Data object from the given Image

  Parameters:
    `image` - image to use
  Returns:
    a FlatField representation of the image
  Throws:
    `IOException`
    `VisADException`

### makeField

    public static FlatField makeField(Image image,
                                      boolean withAlpha)
                               throws IOException,
                                      VisADException

  Create a VisAD Data object from the given Image

  Parameters:
    `image` - image to use
    `withAlpha` - include Alpha in the field if the image ColorModel supports it and the image is not opaque.
  Returns:
    a FlatField representation of the image
  Throws:
    `IOException`
    `VisADException`

### extractImage

    public static Image extractImage(FlatField field,
                                     boolean reverse)

  Converts a flat field of the form `((x, y) -> (r, g, b))` to an AWT Image. If reverse flag is set, image will be upside-down.

### getImageFields

    public static FlatField[] getImageFields(Data data)

### makeSimpleDisplay

    public static DisplayImpl makeSimpleDisplay(DataImpl data)
                                         throws VisADException,
                                                RemoteException

  Throws:
    `VisADException`
    `RemoteException`

### main

    public static void main(String[] argv)
                     throws VisADException,
                            RemoteException

  Throws:
    `VisADException`
    `RemoteException`

### ensureRealTupleType

    public static RealTupleType ensureRealTupleType(MathType type)
                                             throws TypeException,
                                                    VisADException

  Ensures that a MathType is a RealTupleType. Converts if necessary.

  Parameters:
    `type` - The math type to be "converted" to a RealTupleType. It shall be either a RealType, a RealTupleType, or a SetType.
  Returns:
    The RealTupleType version of `type`. If `type` is a RealTupleType, then it is returned; otherwise, if `type` is a RealType, then a RealTupleType containing `type` as the only component is returned; otherwise, if `type` is a SetType, then `((SetType)type).getDomain()` is returned.
  Throws:
    `TypeException` - `type` is the wrong type: it can't be converted into a RealTupleType.
    `VisADException` - Couldn't create necessary VisAD object.

### ensureTupleType

    public static TupleType ensureTupleType(MathType type)
                                     throws VisADException

  Ensures that a MathType is a TupleType. Converts if necessary.

  Parameters:
    `type` - The math type to be "converted" to a TupleType.
  Returns:
    The TupleType version of `type`. If `type` is a TupleType, then it is returned; otherwise, if `type` is a SetType, then `((SetType)type).getDomain()` is returned; otherwise, a TupleType containing `type` as the only component is returned (if `type` is a RealType, then the returned TupleType is a RealTupleType);
  Throws:
    `VisADException` - Couldn't create necessary VisAD object.

### ensureTuple

    public static TupleIface ensureTuple(Data datum)
                                  throws VisADException,
                                         RemoteException

  Ensures that a Data is a Tuple. Creates a Tuple if necessary.

  Parameters:
    `datum` - The math type to be "converted" to a Tuple.
  Returns:
    The Tuple version of `datum`. If `datum` is a Tuple, then it is returned; otherwise, if `datum` is a Real, then a RealTuple containing `datum` as the only component is returned; otherwise, a Tuple containing `datum` as the only component is returned.
  Throws:
    `VisADException` - Couldn't create necessary VisAD object.
    `RemoteException` - Java RMI failure.

### getDomainType

    public static RealTupleType getDomainType(Set set)

  Gets the MathType of the domain of a Set.

  Parameters:
    `set` - A set.
  Returns:
    The MathType of the domain of the Set.

### getDomainType

    public static RealTupleType getDomainType(Function function)
                                       throws VisADException,
                                              RemoteException

  Gets the MathType of the domain of a Function.

  Parameters:
    `function` - A function.
  Returns:
    The MathType of the domain of the function.
  Throws:
    `VisADException` - Couldn't create necessary VisAD object.
    `RemoteException` - Java RMI failure.

### getRangeType

    public static MathType getRangeType(Function function)
                                 throws VisADException,
                                        RemoteException

  Gets the MathType of the range of a Function.

  Parameters:
    `function` - A function.
  Returns:
    The MathType of the range of the function.
  Throws:
    `VisADException` - Couldn't create necessary VisAD object.
    `RemoteException` - Java RMI failure.

### getRangeTupleType

    public static TupleType getRangeTupleType(Function function)
                                       throws VisADException,
                                              RemoteException

  Gets the TupleType of the range of a Function.

  Parameters:
    `function` - A function.
  Returns:
    The TupleType of the range of the function.
  Throws:
    `VisADException` - Couldn't create necessary VisAD object.
    `RemoteException` - Java RMI failure.

### getFlatRangeType

    public static RealTupleType getFlatRangeType(Function function)
                                          throws VisADException,
                                                 RemoteException

  Gets the MathType of the flat-range of a Function.

  Parameters:
    `function` - A function.
  Returns:
    The MathType of the flat-range of the function.
  Throws:
    `VisADException` - Couldn't create necessary VisAD object.
    `RemoteException` - Java RMI failure.

### getRangeDimension

    public static int getRangeDimension(Function function)
                                 throws VisADException,
                                        RemoteException

  Gets the number of components in the range of a Function. NB: This differs from visad.FlatField.getRangeDimension() in that it returns the number of components in the actual range rather than the number of components in the flat range.

  Parameters:
    `function` - A function.
  Returns:
    The number of components in the range of the function.
  Throws:
    `VisADException` - Couldn't create necessary VisAD object.
    `RemoteException` - Java RMI failure.

### getComponentIndex

    public static int getComponentIndex(TupleType tupleType,
                                        MathType componentType)
                                 throws VisADException,
                                        RemoteException

  Gets the index of a component in a TupleType. If the TupleType contains multiple instances of the component, then it is unspecified which component index is returned. This method first looks for an exact match via the `equals(Object)` method. If none is found, then this method looks for an approximate match based on the `equalsExceptNameButUnits(MathType)` method.

  Parameters:
    `tupleType` - The type of the tuple.
    `componentType` - The MathType of the component.
  Returns:
    The index of the component in the tuple or -1 if the component is not in the tuple.
  Throws:
    `VisADException` - Couldn't create necessary VisAD object.
    `RemoteException` - Java RMI failure.

### getComponentIndex

    public static int getComponentIndex(Set set,
                                        MathType componentType)
                                 throws VisADException,
                                        RemoteException

  Gets the index of a component in a Set. If the set contains multiple instances of the component, then it is unspecified which component index is returned.

  Parameters:
    `set` - The Set.
    `componentType` - The MathType of the component.
  Returns:
    The index of the component in the set or -1 if the component is not in the set.
  Throws:
    `VisADException` - Couldn't create necessary VisAD object.
    `RemoteException` - Java RMI failure.

### getComponentIndex

    public static int getComponentIndex(Function function,
                                        MathType componentType)
                                 throws VisADException,
                                        RemoteException

  Gets the index of a component in the range of a Function. If the range contains multiple instances of the component, then it is unspecified which component index is returned.

  Parameters:
    `function` - The Function.
    `componentType` - The MathType of the component.
  Returns:
    The index of the component in the range of the field or -1 if the component is not in the range of the field (NB: this is not the flat-range index).
  Throws:
    `VisADException` - Couldn't create necessary VisAD object.
    `RemoteException` - Java RMI failure.

### ensureRange

    public static Field ensureRange(Field field,
                                    MathType newRangeType)
                             throws UnimplementedException,
                                    TypeException,
                                    VisADException,
                                    RemoteException

  Ensures that the range of a Field is a given type. Extracts from the input field only if necessary.

  Parameters:
    `field` - The input field.
    `newRangeType` - The desired type of range for the resulting field.
  Returns:
    A field with the desired range type. The range data will be missing, however, if all of it couldn't be extracted from the input Field (i.e. RETURN_VALUE`.isMissing()` will be true.
  Throws:
    `UnimplementedException` - The desired range type is a TupleType and not a RealTupleType.
    `TypeException` - The new range type cannot be the range of a field.
    `VisADException` - Couldn't create necessary VisAD object.
    `RemoteException` - Java RMI failure.

### consolidate

    public static Field consolidate(Field[] fields)
                             throws FieldException,
                                    TypeException,
                                    VisADException,
                                    RemoteException

  Consolidates fields.

  Parameters:
    `fields` - The fields to consolidate. Each field shall have the same FunctionType.
  Returns:
    The input Fields consolidated into one Field. The domain shall be a GriddedSet comprising the union of the sample points of the fields. The FunctionType shall be the same as that of the input Field-s. When more than one input Field has valid range data for the same domain point, it is unspecified which range datum is used for the output Field.
  Throws:
    `FieldException` - The Field array has zero length.
    `TypeException` - Input Field-s not all same type.
    `VisADException` - Couldn't create necessary VisAD object.
    `RemoteException` - Java RMI failure.

### createGriddedSet

    public static GriddedSet createGriddedSet(FlatField field,
                                              boolean copy)
                                       throws VisADException,
                                              RemoteException

  Creates a GriddedSet from a FlatField. The GriddedSet will be created from the domain and flat-range of the FlatField. The first components in the tuples of the GriddedSet will come from the domain of the FlatField and the remaining components will come from the range of the FlatField. Note that, because a GriddedSet doesn't have the ability to contain values in small primitives (e.g. byte, short), the returned set may be significantly larger than the input field.

  Parameters:
    `field` - The FlatField from which to create a GriddedSet.
    `copy` - Whether or not to copy the range values from the field (i.e. `field.getFloats(copy)` ).
  Returns:
    The GriddedSet corresponding to the input FlatField.
  Throws:
    `VisADException` - Couldn't create necessary VisAD object.
    `RemoteException` - Java RMI failure.

### simplify

    public static MathType simplify(MathType type)
                             throws VisADException

  Simplifies a MathType. Removes all enclosing, single-component TupleType-s until the "core" is revealed (e.g. ScalarType, multi-component TupleType).

  Parameters:
    `type` - The MathType to be simplified.
  Returns:
    The simplest form corresponding to `type`.
  Throws:
    `VisADException` - Couldn't create necessary VisAD object.

### getRealTypes

    public static int getRealTypes(Data data,
                                   Vector v)
                            throws VisADException,
                                   RemoteException

  Deprecated. Use getScalarTypes(Data, Vector) instead.

  Throws:
    `VisADException`
    `RemoteException`

### getRealTypes

    public static int getRealTypes(Data[] data,
                                   Vector v,
                                   boolean keepDupl,
                                   boolean doCoordSys)
                            throws VisADException,
                                   RemoteException

  Deprecated. Use getScalarTypes(Data[], Vector, boolean, boolean) instead.

  Throws:
    `VisADException`
    `RemoteException`

### getScalarTypes

    public static int getScalarTypes(Data data,
                                     Vector v)
                              throws VisADException,
                                     RemoteException

  Obtains a Vector consisting of all ScalarTypes present in a Data object's MathType.

  Parameters:
    `data` - The Data from which to extract the ScalarTypes.
    `v` - The Vector in which to store the ScalarTypes.
  Returns:
    The number of duplicate ScalarTypes found.
  Throws:
    `VisADException` - Couldn't parse the Data's MathType.
    `RemoteException` - Couldn't obtain the remote Data's MathType.

### getScalarTypes

    public static int getScalarTypes(Data[] data,
                                     Vector v,
                                     boolean keepDupl,
                                     boolean doCoordSys)
                              throws VisADException,
                                     RemoteException

  Obtains a Vector consisting of all ScalarTypes present in an array of Data objects' MathTypes.

  Parameters:
    `data` - The array of Data from which to extract the ScalarTypes.
    `v` - The Vector in which to store the ScalarTypes.
    `keepDupl` - Whether to add a RealType to the Vector when it is already present there.
    `doCoordSys` - Whether to include ScalarTypes from CoordinateSystem references.
  Returns:
    The number of duplicate ScalarTypes found.
  Throws:
    `VisADException` - Couldn't parse a Data's MathType.
    `RemoteException` - Couldn't obtain a remote Data's MathType.

### guessMaps

    public static ScalarMap[] guessMaps(MathType[] types,
                                        boolean allow3d)

  Attempts to guess a good set of mappings for a display containing Data objects of the given types. The algorithm simply returns mappings for the first successfully guessed dataset.

### convertMapsToString

    public static String convertMapsToString(Vector v)

  Converts the given vector of mappings to an easy-to-read String form.

### convertMapsToString

    public static String convertMapsToString(ScalarMap[] sm)

  Converts the given array of mappings to an easy-to-read String form.

### convertStringToMaps

    public static ScalarMap[] convertStringToMaps(String mapString,
                                                  Data data,
                                                  boolean showErrors)

  Converts the given map string to its corresponding array of mappings.

  Parameters:
    `mapString` - The String from which to extract the ScalarMaps.
    `data` - The Data object to search for valid ScalarTypes.
    `showErrors` - Whether to output errors to stdout.

### convertStringToMaps

    public static ScalarMap[] convertStringToMaps(String mapString,
                                                  Data[] data,
                                                  boolean showErrors)

  Converts the given map string to its corresponding array of mappings.

  Parameters:
    `mapString` - The String from which to extract the ScalarMaps.
    `data` - The Data objects to search for valid ScalarTypes.
    `showErrors` - Whether to output errors to stdout.

### convertStringToMaps

    public static ScalarMap[] convertStringToMaps(String mapString,
                                                  Vector types,
                                                  boolean showErrors)

  Converts the given map string to its corresponding array of mappings.

  Parameters:
    `mapString` - The String from which to extract the ScalarMaps.
    `types` - List of valid ScalarTypes.
    `showErrors` - Whether to output errors to stdout.

### stringsToTuple

    public static Tuple stringsToTuple(String[] s)

  Converts an array of strings into a VisAD Tuple.

  Parameters:
    `s` - The array of strings to be converted to a VisAD Tuple.
  Returns:
    VisAD Tuple, or null if Tuple could not be created.

### stringsToTuple

    public static Tuple stringsToTuple(String[] s,
                                       boolean printStackTraces)

  Converts an array of strings into a VisAD Tuple.

  Parameters:
    `s` - The array of strings to be converted to a VisAD Tuple.
    `printStackTraces` - `true` if the stack trace for any exception should be printed.
  Returns:
    VisAD Tuple, or null if Tuple could not be created.

### tupleToStrings

    public static String[] tupleToStrings(Tuple t)

  Converts a VisAD tuple into an array of strings.

  Parameters:
    `t` - The VisAD Tuple to be converted to an array of strings.
  Returns:
    Array of Strings, or null if array could not be created.

### tupleToStrings

    public static String[] tupleToStrings(Tuple t,
                                          boolean printStackTraces)

  Converts a VisAD tuple into an array of strings.

  Parameters:
    `t` - The VisAD Tuple to be converted to an array of strings.
    `printStackTraces` - `true` if the stack trace for any exception should be printed.
  Returns:
    Array of Strings, or null if array could not be created.

### isSerializable

    public static boolean isSerializable(Object obj)

  Verify that an object is Serializable by attempting to serialize it.

  Parameters:
    `obj` - An object which needs to be serialized
  Returns:
    `true` if the object is Serializable, false otherwise.

### isSerializable

    public static boolean isSerializable(Object obj,
                                         boolean printStackTraces)

  Verify that an object is Serializable by attempting to serialize it.

  Parameters:
    `obj` - An object which needs to be serialized
    `printStackTraces` - `true` if the stack trace for any exception should be printed.
  Returns:
    `true` if the object is Serializable, false otherwise.

### makeLocal

    public static DataImpl makeLocal(Data data)

  Converts a remote Data object to a local Data object.

  Parameters:
    `data` - The Data object to be made local.
  Returns:
    Local Data object, or null if Data could not be converted.

### makeLocal

    public static DataImpl makeLocal(Data data,
                                     boolean printStackTraces)

  Converts a remote Data object to a local Data object.

  Parameters:
    `data` - The Data object to be made local.
    `printStackTraces` - `true` if the stack trace for any exception should be printed.
  Returns:
    Local Data object, or null if Data could not be converted.

### getSample

    public static RealTuple getSample(Set set,
                                      int index)
                               throws VisADException,
                                      RemoteException

  Gets the specified sample of a VisAD Set.

  Parameters:
    `set` - The set to have a sample returned.
    `index` - The index of the sample to be returned.
  Returns:
    The sample at the specified index. Will be empty if the index is out-of-bounds. Will have a single component if the set is one-dimensional.
  Throws:
    `VisADException` - Couldn't create necessary VisAD object.
    `RemoteException` - Java RMI failure.

### getRangeUnits

    public static Unit[] getRangeUnits(FlatField field)

  Gets the units of the (flat) components of the range of a FlatField.

  Parameters:
    `field` - The FlatField.
  Returns:
    The units of the (flat) components of the range of the FlatField. Won't be `null`.