Package uk.ac.starlink.array
Class NDShape
java.lang.Object
uk.ac.starlink.array.NDShape
- All Implemented Interfaces:
Cloneable
- Direct Known Subclasses:
OrderedNDShape
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
FieldsModifier and TypeFieldDescriptionstatic final long
The default value of the origin in each dimension; its value is 1. -
Constructor Summary
ConstructorsConstructorDescriptionNDShape
(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.Creates an NDShape object with the same origin and dimensions as an existing one. -
Method Summary
Modifier and TypeMethodDescriptionclone()
boolean
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[]
Returns the exclusive upper limits in each dimension of the NDShape.int
Returns the dimensionality of the NDShape.long
Returns the number of cells in the array represented by this NDShape.long[]
Returns the origin in each dimension of the NDShape.long[]
Returns the inclusive upper limits in each dimension of the NDShape.int
hashCode()
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 ofint
values to an array oflong
values.static int[]
longsToInts
(long[] larray) Convenience method for converting an array oflong
values to an array ofint
values.boolean
Indicates whether another object represents the same shape as this.toString()
static String
toString
(long[] pos) Returns a string representation of a position.static String
Returns a string representation of a shape.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.
-
Field Details
-
DEFAULT_ORIGIN
public static final long DEFAULT_ORIGINThe 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:
-
-
Constructor Details
-
NDShape
public NDShape(long[] origin, long[] dims) Creates an NDShape object from its origin and dimensions.- Parameters:
origin
- an array representing the origindims
- 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 origindims
- 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 beDEFAULT_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 beDEFAULT_ORIGIN
.- Parameters:
dims
- an array representing the dimension extents- Throws:
IllegalArgumentException
- if any of the dimensions are not positive
-
NDShape
Creates an NDShape object with the same origin and dimensions as an existing one. Note this can be used to construct an object of classNDShape
from anOrderedNDShape
.- Parameters:
shape
- existing NDShape object
-
-
Method Details
-
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
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
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
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
-
hashCode
public int hashCode() -
clone
-
toString
-
toString
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
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
Turns a string specification of a shape into an NDShape object. This method is effectively the inverse oftoString()
.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
or50+100,50+100
Straggling whitespace is tolerated.- Parameters:
str
- the string representing the shape.- Returns:
- the corresponding NDShape
- Throws:
IllegalArgumentException
- ifstr
does not match one of the understood formats for a shape
-
intsToLongs
public static long[] intsToLongs(int[] iarray) Convenience method for converting an array ofint
values to an array oflong
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 oflong
values to an array ofint
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 oflarray
is out of the rangeInteger.MIN_VALUE..Integer.MAX_VALUE
-