NDShape (Starlink-UK API)

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

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

OrderedNDShape
```
public class NDShape
extends Object
implements Cloneable
```
Represents the shape of an N-dimensional rectangular array. The shape is represented by an N-element array of longs giving the origin (coordinates of the first pixel) and another N-element array of longs giving the dimensions (number of pixels in each dimension). This shape is considered to contain pixels with coordinate origin[i]<=pos[i]<origin[i]+dims[i] in each dimension i. An Iterator over all these pixels may be obtained by using the OrderedNDShape class.
This object is immutable.

Version:

$Id$

Author:

Mark Taylor (Starlink)

Field Summary

Fields
Modifier and Type Field and Description

static long DEFAULT_ORIGIN
The default value of the origin in each dimension; its value is 1.

Fields
Modifier and Type	Field and Description
`static long`	`DEFAULT_ORIGIN` The default value of the origin in each dimension; its value is 1.

Constructor Summary

Constructors
Constructor and Description
`NDShape(int[] dims)` Creates an NDShape object with a default origin from an integer array of dimensions.
`NDShape(long[] dims)` Creates an NDShape object with a default origin from its dimensions.
`NDShape(long[] origin, int[] dims)` Creates an NDShape object from its origin and an integer array of dimensions.
`NDShape(long[] origin, long[] dims)` Creates an NDShape object from its origin and dimensions.
`NDShape(NDShape shape)` Creates an NDShape object with the same origin and dimensions as an existing one.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Object`	`clone()`
`boolean`	`equals(Object other)`
`static NDShape`	`fromString(String str)` Turns a string specification of a shape into an NDShape object.
`long[]`	`getDims()` Returns the extents in each dimension of the NDShape.
`long[]`	`getLimits()` Returns the exclusive upper limits in each dimension of the NDShape.
`int`	`getNumDims()` Returns the dimensionality of the NDShape.
`long`	`getNumPixels()` Returns the number of cells in the array represented by this NDShape.
`long[]`	`getOrigin()` Returns the origin in each dimension of the NDShape.
`long[]`	`getUpperBounds()` Returns the inclusive upper limits in each dimension of the NDShape.
`int`	`hashCode()`
`NDShape`	`intersection(NDShape other)` Returns a NDShape giving the intersection between this shape and another one.
`static long[]`	`intsToLongs(int[] iarray)` Convenience method for converting an array of `int` values to an array of `long` values.
`static int[]`	`longsToInts(long[] larray)` Convenience method for converting an array of `long` values to an array of `int` values.
`boolean`	`sameShape(NDShape other)` Indicates whether another object represents the same shape as this.
`String`	`toString()`
`static String`	`toString(long[] pos)` Returns a string representation of a position.
`static String`	`toString(NDShape shape)` Returns a string representation of a shape.
`NDShape`	`union(NDShape other)` Returns a NDShape giving the union of this shape and another one.
`boolean`	`within(long[] pos)` Indicates whether a given point is within this shape.

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

- Field Detail
  - DEFAULT_ORIGIN
```
public static final long DEFAULT_ORIGIN
```
    The default value of the origin in each dimension; its value is 1. This value is used by the constructors which do not take origin arrays.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - NDShape
```
public NDShape(long[] origin,
               long[] dims)
```
    Creates an NDShape object from its origin and dimensions.
    
    Parameters:
    
    origin - an array representing the origin
    
    dims - an array representing the dimension extents
    
    Throws:
    
    IllegalArgumentException - if origin and dims have different lengths or any of the dimensions are not positive
  - NDShape
```
public NDShape(long[] origin,
               int[] dims)
```
    Creates an NDShape object from its origin and an integer array of dimensions.
    
    Parameters:
    
    origin - an array representing the origin
    
    dims - an array representing the dimension extents
    
    Throws:
    
    IllegalArgumentException - if origin and dims have different lengths or any of the dimensions are not positive
  - NDShape
```
public NDShape(long[] dims)
```
    Creates an NDShape object with a default origin from its dimensions. Each element of the origin is taken to be DEFAULT_ORIGIN.
    
    Parameters:
    
    dims - an array representing the dimension extents
    
    Throws:
    
    IllegalArgumentException - if any of the dimensions are not positive
  - NDShape
```
public NDShape(int[] dims)
```
    Creates an NDShape object with a default origin from an integer array of dimensions. Each element of the origin is taken to be DEFAULT_ORIGIN.
    
    Parameters:
    
    dims - an array representing the dimension extents
    
    Throws:
    
    IllegalArgumentException - if any of the dimensions are not positive
  - NDShape
```
public NDShape(NDShape shape)
```
    Creates an NDShape object with the same origin and dimensions as an existing one. Note this can be used to construct an object of class NDShape from an OrderedNDShape.
    
    Parameters:
    
    shape - existing NDShape object
- Method Detail
  - getOrigin
```
public long[] getOrigin()
```
    Returns the origin in each dimension of the NDShape.
    
    Returns:
    
    an array giving the origin of this shape. Changing this array will not affect the NDShape object.
  - getDims
```
public long[] getDims()
```
    Returns the extents in each dimension of the NDShape.
    
    Returns:
    
    an array giving the dimensions of this shape. Changing this array will not affect the NDShape object.
  - getLimits
```
public long[] getLimits()
```
    Returns the exclusive upper limits in each dimension of the NDShape. limits[i]=origin[i]+dims[i].
    
    Returns:
    
    an array giving the upper limits of this shape. Changing this array will not affect the NDShape object.
  - getUpperBounds
```
public long[] getUpperBounds()
```
    Returns the inclusive upper limits in each dimension of the NDShape. limits[i]=origin[i]+dims[i]-1.
    
    Returns:
    
    an array giving the upper limits of this shape. Changing this array will not affect the NDShape object.
  - getNumDims
```
public int getNumDims()
```
    Returns the dimensionality of the NDShape.
    
    Returns:
    
    the number of dimensions the array has.
  - getNumPixels
```
public long getNumPixels()
```
    Returns the number of cells in the array represented by this NDShape.
    
    Returns:
    
    the number of cells in the array
  - intersection
```
public NDShape intersection(NDShape other)
```
    Returns a NDShape giving the intersection between this shape and another one.
    
    Parameters:
    
    other - the other shape
    
    Returns:
    
    a new NDShape representing the overlap between this and other. If there is no such intersection (no pixels present in both) then null is returned.
    
    Throws:
    
    IllegalArgumentException - if the other has a different dimensionality to this shape
  - union
```
public NDShape union(NDShape other)
```
    Returns a NDShape giving the union of this shape and another one.
    
    Parameters:
    
    other - the other shape
    
    Returns:
    
    a new NDShape, the smallest possible which contains all the pixels in this one and all the pixels in other
    
    Throws:
    
    IllegalArgumentException - if the other has a different dimensionality to this shape
  - within
```
public boolean within(long[] pos)
```
    Indicates whether a given point is within this shape.
    
    Parameters:
    
    pos - the coordinates of a position
    
    Returns:
    
    true if each for each dimension i, origin[i]<=pos[i]<origin[i]+dims[i]
  - sameShape
```
public boolean sameShape(NDShape other)
```
    Indicates whether another object represents the same shape as this. Two shapes are the same if they have the same origin and dimensions. Note this call differs from the equals method in that the shape of an NDShape may be compared with that of an object of one of its subclasses.
    
    Parameters:
    
    other - an NDShape object for comparison with this one
  - equals
```
public boolean equals(Object other)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - clone
```
public Object clone()
```
    Overrides:
    
    clone in class Object
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - toString
```
public static String toString(NDShape shape)
```
    Returns a string representation of a shape. This currently returns a string like "(10+5,20+8)" for a shape with origin (10,20) and dimensions (5,8).
    As a special case, if any of the origin elements has the value Long.MIN_VALUE, then a "*" is written in the corresponding position.
    
    Parameters:
    
    shape - the shape to describe
    
    Returns:
    
    a string describing shape
  - toString
```
public static String toString(long[] pos)
```
    Returns a string representation of a position. This is a utility function which returns a string indicating the value of a position vector, in a form like "(10,20,23)".
    As a special case, if any of the elements has the value Long.MIN_VALUE, then a "*" is written in the corresponding position.
    
    Parameters:
    
    pos - a vector of longs
    
    Returns:
    
    a string representation of pos
  - fromString
```
public static NDShape fromString(String str)
```
    Turns a string specification of a shape into an NDShape object. This method is effectively the inverse of toString().
    Each dimension specification is separated from the next using a comma, and may be given as lower:upper inclusive bounds or origin+dimension. So a 100x100 array with origin (50,50) may be written:
```
     50:149,50:149
 
```
    or
```
     50+100,50+100
 
```
    Straggling whitespace is tolerated.
    Parameters:
    
    str - the string representing the shape.
    
    Returns:
    
    the corresponding NDShape
    
    Throws:
    
    IllegalArgumentException - if str does not match one of the understood formats for a shape
  - intsToLongs
```
public static long[] intsToLongs(int[] iarray)
```
    Convenience method for converting an array of int values to an array of long values.
    
    Parameters:
    
    iarray - an array of integers
    
    Returns:
    
    an array of long integers with the same values as iarray
  - longsToInts
```
public static int[] longsToInts(long[] larray)
```
    Convenience method for converting an array of long values to an array of int values. Unlike a normal java typecast, if a conversion overflow occurs an IndexOutOfBoundsException will be thrown.
    
    Parameters:
    
    larray - an array of long integers
    
    Returns:
    
    an array of integers with the same values as larray
    
    Throws:
    
    IndexOutOfBoundsException - if any of the elements of larray is out of the range Integer.MIN_VALUE..Integer.MAX_VALUE

Class NDShape

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_ORIGIN

Constructor Detail

NDShape

NDShape

NDShape

NDShape

NDShape

Method Detail

getOrigin

getDims

getLimits

getUpperBounds

getNumDims

getNumPixels

intersection

union

within

sameShape

equals

hashCode

clone

toString

toString

toString

fromString

intsToLongs

longsToInts