Package uk.ac.starlink.array

# Class OrderedNDShape

java.lang.Object
uk.ac.starlink.array.NDShape
uk.ac.starlink.array.OrderedNDShape

All Implemented Interfaces:
  `Cloneable`

public class OrderedNDShape extends NDShape implements Cloneable
Represents the arrangement of pixels within an N-dimensional array. Instances of this class are `NDShape`s with an additional ordering specified which indicates the sequence in which pixels are encountered. This class thus defines a mapping between an ordered sequence of positions and their coordinates in N-dimensional space.

Version:
  $Id$
Author:
  Mark Taylor (Starlink)

## Field Summary

### Fields inherited from class uk.ac.starlink.array.NDShape

`DEFAULT_ORIGIN`

## Constructor Summary

Constructors
Constructor
Description
`OrderedNDShape(long[] origin, long[] dims, Order order)`
Creates an OrderedNDShape from its origin, dimensions and ordering.
`OrderedNDShape(long[] dims, Order order)`
Creates an OrderedNDShape with a default origin from its dimensions and ordering.
`OrderedNDShape(NDShape shape)`
Creates a new OrderedNDShape from an NDShape.
`OrderedNDShape(NDShape shape, Order order)`
Creates an OrderedNDShape from a NDShape and an ordering.

## Method Summary

Modifier and Type
Method
Description
`Object`
`clone()`
`boolean`
`equals(Object other)`
Indicates whether another object is equivalent to this one.
`Order`
`getOrder()`
Gets the ordering scheme of this object.
`int`
`hashCode()`
`long[]`
`offsetToPosition(long offset)`
Determines the coordinates of a pixel at a given offset within the pixel sequence.
`Iterator`
`pixelIterator()`
Returns an Iterator which will iterate over all the pixels in this OrderedNDShape's pixel sequence.
`Iterator`
`pixelIterator(long start, long length)`
Returns an Iterator which will iterate over a range of pixels in this OrderedNDShape's pixel sequence.
`long`
`positionToOffset(long[] pos)`
Returns the offset of a pixel having given coordinates within the sequence of pixels defined by this OrderedNDShape.
`boolean`
`sameSequence(OrderedNDShape other)`
Indicates whether another object represents the same pixel sequence as this.
`String`
`toString()`

### Methods inherited from class uk.ac.starlink.array.NDShape

`fromString, getDims, getLimits, getNumDims, getNumPixels, getOrigin, getUpperBounds, intersection, intsToLongs, longsToInts, sameShape, toString, toString, union, within`

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

`finalize, getClass, notify, notifyAll, wait, wait, wait`

## Constructor Details

### OrderedNDShape

public OrderedNDShape(long[] origin, long[] dims, Order order)
Creates an OrderedNDShape from its origin, dimensions and ordering.

Parameters:
  `origin` - an array representing the origin
  `dims` - an array representing the dimension extents
  `order` - an Order object specifying the pixel ordering scheme. If the null value is supplied, an arbitrary ordering scheme will be applied.
Throws:
  `IllegalArgumentException` - if origin and dims have different lengths or any of the dimensions are not positive

### OrderedNDShape

public OrderedNDShape(long[] dims, Order order)
Creates an OrderedNDShape with a default origin from its dimensions and ordering. Each element of the origin array has the value `NDShape.DEFAULT_ORIGIN`.

Parameters:
  `dims` - an array representing the dimension extents
  `order` - an Order object specifying the pixel ordering scheme. If the null value is supplied, an arbitrary ordering scheme will be applied.
Throws:
  `IllegalArgumentException` - if any of the dimensions are not positive

### OrderedNDShape

public OrderedNDShape(NDShape shape, Order order)
Creates an OrderedNDShape from a NDShape and an ordering.

Parameters:
  `shape` - a NDShape object
  `order` - an Order object specifying the pixel ordering scheme If the null value is supplied, an arbitrary ordering scheme will be applied.

### OrderedNDShape

public OrderedNDShape(NDShape shape)
Creates a new OrderedNDShape from an NDShape. If `shape` is in fact an instance of `OrderedNDShape`, the created object will be equivalent to it. If not, a new OrderedNDShape object will be created with an arbitrary ordering scheme.

Parameters:
  `shape` - an NDShape or OrderedNDShape object

## Method Details

### getOrder

public Order getOrder()
Gets the ordering scheme of this object.

Returns:
  an Order object indicating the ordering scheme

### pixelIterator

public Iterator pixelIterator(long start, long length)
Returns an Iterator which will iterate over a range of pixels in this OrderedNDShape's pixel sequence. The `next` method of the returned Iterator returns an array of longs giving the coordinates of the next pixel in the sequence. Note that this long array is the same object every time, but its contents change at each iteration. It should not be modified by clients.

Parameters:
  `start` - the first offset in the pixel sequence over which to iterate
  `length` - the number of pixels over which to iterate
Returns:
  an Iterator over cells
Throws:
  `IllegalArgumentException` - if start and length would imply iteration outside of this shape or length is negative

### pixelIterator

public Iterator pixelIterator()
Returns an Iterator which will iterate over all the pixels in this OrderedNDShape's pixel sequence. The `next` method of the returned Iterator returns an array of longs giving the coordinates of the next pixel in the sequence. Note that this long array is the same object every time, but its contents change at each iteration. It should not be modified by clients.

Equivalent to `pixelIterator(0,getNumPixels())`;

Returns:
  an Iterator over cells

### positionToOffset

public long positionToOffset(long[] pos)
Returns the offset of a pixel having given coordinates within the sequence of pixels defined by this OrderedNDShape. It will validate its input, and so may not be maximally efficient.

Parameters:
  `pos` - a coordinate vector giving a pixel position
Returns:
  the offset into this shape's pixel sequence at which the pixel at `pos` occurs
Throws:
  `IndexOutOfBoundsException` - if pos is outside this shape

### offsetToPosition

public long[] offsetToPosition(long offset)
Determines the coordinates of a pixel at a given offset within the pixel sequence. It will validate its input, and so may not be maximally efficient.

Parameters:
  `offset` - an offset into the list of pixels
Returns:
  the coordinates of the pixel at `offset`
Throws:
  `IndexOutOfBoundsException` - if `offset` is outside this shape

### clone

public Object clone()

Overrides:
  `clone` in class `NDShape`

### sameSequence

public boolean sameSequence(OrderedNDShape other)
Indicates whether another object represents the same pixel sequence as this. Two shapes are the same if they have the same origins, dimensions and ordering scheme. A true result from this method implies that pixel iterators returned from the two objects will behave in exactly the same way (present the same pixel positions in the same order).

Parameters:
  `other` - the shape to compare with this one
Returns:
  true iff the pixel sequences are the same

### equals

public boolean equals(Object other)
Indicates whether another object is equivalent to this one.

Overrides:
  `equals` in class `NDShape`
Parameters:
  `other` - an OrderedNDShape object for comparison with this one

### hashCode

public int hashCode()

Overrides:
  `hashCode` in class `NDShape`

### toString

public String toString()

Overrides:
  `toString` in class `NDShape`