Package uk.ac.starlink.array

# Class NDArrays

java.lang.Object
uk.ac.starlink.array.NDArrays

public class NDArrays extends Object
Utility methods for NDArray manipulation.

Author:
  Mark Taylor (Starlink)

## Method Summary

Modifier and Type
Method
Description
`static void`
`copy(NDArray src, NDArray dest)`
Copies the data from one NDArray into another.
`static boolean`
`equals(NDArray nda1, NDArray nda2)`
Tests two NDArrays for equivalence.
`static NDArray`
`scratchCopy(ArrayImpl impl)`
Provides an independent `NDArray` based on a readable `ArrayImpl`, with data stored in a scratch array.
`static NDArray`
`scratchCopy(NDArray nda)`
Provides an independent copy of a readable `NDArray` with data stored in a scratch array.
`static NDArray`
`toRequiredArray(NDArray nda, Requirements req)`
Returns an NDArray whose type, shape, ordering scheme etc are described by a supplied `Requirements` object.

### Methods inherited from class java.lang.Object

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

## Method Details

### copy

public static void copy(NDArray src, NDArray dest) throws IOException
Copies the data from one NDArray into another. The two must have the same shape (origin and dimensions), though may have different pixel ordering schemes. They may have different primitive types and/or bad values; out-of-range values in narrowing conversions result in bad values. An effort is made to perform the copy in the most efficient way possible.

Parameters:
  `src` - the source NDArray
  `dest` - the destination NDArray
Throws:
  `IOException` - if an I/O error occurs
  `IllegalArgumentException` - if src and dest do not match in origin, dimensions or type
  `UnsupportedOperationException` - if src is not readable or dest is not writable
See Also:
  - `TypeConverter`

### equals

public static boolean equals(NDArray nda1, NDArray nda2) throws IOException
Tests two NDArrays for equivalence. Returns true only if the data of both are equivalent; this means that the type and shape must be the same, but not necessarily the pixel ordering scheme, URL, writability etc. A bad value in one array is considered equivalent to a bad value in the other, even if the two do not have the same magic bad value.

Parameters:
  `nda1` - first NDArray
  `nda2` - second NDArray
Returns:
  true if and only if the data and shape of `nda1` and `nda2` are equivalent
Throws:
  `IOException`

### toRequiredArray

public static NDArray toRequiredArray(NDArray nda, Requirements req) throws IOException
Returns an NDArray whose type, shape, ordering scheme etc are described by a supplied `Requirements` object. The required shape must have the same dimensionality as that of the base array, but there are no other restrictions on shape - it may be wholly, partially, or not at all within the base array. In the case that the required (and hence returned) shape differs from that of the base array, any given position (coordinate vector) will refer to the same pixel value in both base and returned NDArray. Reading a pixel in the returned array from a position which is outside the bounds of the base array will result in a bad value. Writing such a pixel will have no effect on the base array.

The mode field of the Requirements should be set to indicate the use which will be made of the returned NDArray. It cannot be used to turn a non-readable or non-writable NDArray into a readable or writable one, but controls copying of data - for READ or UPDATE access the returned array is guaranteed to contain the same data as the base array, and for WRITE or UPDATE access writing to the returned array is guaranteed to modify the base array. If null, a mode will be chosen based on the read/writability of the base NDArray, which ought to give correct results, but may cause more work to be done than is necessary.

Parameters:
  `nda` - the NDArray on which to base the result
  `req` - a Requirements object indicating the characteristics required. If `null`, then `nda` is returned with no further action
Returns:
  an NDArray with the same data as nda and the characteristics indicated by req
Throws:
  `IOException` - if a new scratch array has to be created and filled, and an I/O error occurs at this stage
  `IllegalArgumentException` - if mode implies an access mode not provided by the base array

### scratchCopy

public static NDArray scratchCopy(NDArray nda) throws IOException
Provides an independent copy of a readable `NDArray` with data stored in a scratch array. The data is copied from the base array but the returned copy will have random access, read access and write access, and is likely to have mapped access (though cannot do so in the case in which the requested dimensions imply more than Integer.MAX_VALUE pixels). Reads and writes from/to the data of the copy have no effect on the original and vice versa.

Invoking this method is equivalent to creating an scratch array and copying the data from the base `NDArray` into it.

A sensible decision about the backing store to use (memory or disk) is made by this class on the basis of the size of array requested.

Parameters:
  `nda` - the NDArray whose data will be copied
Returns:
  a scratch NDArray holding the same data as nda
Throws:
  `IOException` - if an I/O error occurs during the copying
  `UnsupportedOperationException` - if `nda` is not readable or it does not support multiple access and its `getAccess` method has already been called
  `IllegalStateException` - if close has been called on `nda`

### scratchCopy

public static NDArray scratchCopy(ArrayImpl impl) throws IOException
Provides an independent `NDArray` based on a readable `ArrayImpl`, with data stored in a scratch array.

This convenience method does just the same as invoking

        NDArrays.scratchCopy( new BridgeNDArray( impl ) )

Parameters:
  `impl` - the ArrayImpl whose data will be copied
Returns:
  a scratch NDArray backed by the same data as nda
Throws:
  `IOException` - if an I/O error occurs during the copying
See Also:
  - `scratchCopy(NDArray)`