Image¶

class hsi.HSImage¶

A generic HS image object.

static from_numpy(array, interleave=Ellipsis, /)¶

Create new in-memory image from a NumPy array.

Note that the array memory is always copied. The meaning of each axis is determined by the interleave parameter.

Parameters:

array (ndarray) – The input array.
interleave (Interleave) – The interleave format to use for the image.

Returns:

An in-memory image that can be efficiently accessed.

Return type:

HSImage

static from_numpy_with_header(array, header, /)¶

Create new in-memory image from a NumPy array and header.

Note that the array memory is always copied. The meaning of each axis is determined by the interleave parameter.

Parameters:

array (ndarray) – The input array.
header (HSIHeader) – The interleave format to use for the image.

Returns:

An in-memory image that can be efficiently accessed.

Return type:

HSImage

add(rhs)¶

Add an image or scalar to this image.

If the operand is a scalar, the operation is right scalar addition. If it is an image, the operation is elementwise addition with optional broadcasting.

Broadcasting is used for the operand if it is not of the same shape as the base image. Broadcasting uses the ndarray/numpy broadcasting rules.

Parameters:: rhs (HSImage | int | float) – Operand. Will possibly be broadcast to the base image shape.
Returns:: A new image. The shape is the same as the base image.
Return type:: HSImage

add_left(lhs)¶

Perform left scalar “addition”.

Parameters:: lhs (int | float) – The left operand.
Returns:: A new image. The shape is the same as the base image.
Trype:: HSImage

apply(func, *args, **kwargs)¶

array_plane(index, axis)¶

Get a single plane along a specified axis.

Parameters:

int (index) – The index to retrieve.
axis (Axis) – The axis to index along.

Returns:

A two-dimensional array representing an axis-aligned plane in the data cube.

Return type:

ndarray

array_plane_crop(index, axis, crop)¶

Get a single plane along a specified axis with cropping.

Dont use this method. Instead, slice the cube and then use `array_plane`

Parameters:

int (index) – The index to retrieve.
axis (Axis) – The axis to index along.
crop (Crop) – Crop info.

Returns:

A two-dimensional array representing an axis-aligned plane in the data cube.

Return type:

ndarray

as_dtype(dtype, /)¶

Convert the image to the specified type.

Parameters:: dtype (DType) – Target datatype.
Returns:: The transformed image.
Return type:: HSImage

binning(bin_size, axis, /)¶

Perform software binning along the specified axis.

Parameters:

bin_size (int) – The size of the bins.
axis (hsi.Axis) – The binning axis.

Returns:

A new image with the shape along the binning axis divided by the bin_size.

Return type:

HSImage

clip(min, max, /)¶

Clamp values to the provided interval.

Parameters:

min (float) – Minimum value in output.
max (float) – Maximum value in output.

Returns:

Image where all values are in the interval (min, max).

Return type:

HSImage

div(rhs)¶

Divide by an image or scalar to this image.

If the operand is a scalar, the operation is right scalar division. If it is an image, the operation is elementwise division with optional broadcasting.

Broadcasting is used for the operand if it is not of the same shape as the base image. Broadcasting uses the ndarray/numpy broadcasting rules.

Parameters:: rhs (HSImage | int | float) – Operand. Will possibly be broadcast to the base image shape.
Returns:: A new image. The shape is the same as the base image.
Return type:: HSImage

div_left(lhs)¶

Perform left scalar division.

Parameters:: lhs (int | float) – The left operand.
Returns:: A new image. The shape is the same as the base image.
Trype:: HSImage

dot(operand, axis, /)¶

Perform matrix-vector or matrix-matrix multiplication between this image and an array.

The multiplication is performed over the specified axis. For example, if we have an LxSxB image multiplied by an MxN matrix on the bands axis, M=B and the result will be an LxSxN image.

If the operand is a vector, the output is always of size 1 along the axis. For example, an LxSxB image multiplied by an M vector over the sample axis produces an Lx1xB result.

Parameters:

operand (ndarray) – A M or MxN array used as operand.
axis (Axis) – The inner axis. The corresponding image axis must be of length M.

Returns:

The resulting image.

Return type:

HSImage

ensure_dtype(dtype)¶

Efficiently convert to the target dtype if necessary.

Parameters:: dtype (DType) – The target dtype.
Returns:: A new HSImage of the desired dtype. Conversion only happens if it is necessary.
Return type:: HSImage

mean_axis(axis, /)¶

Calculate the mean over the specified axis.

Parameters:: axis (Axis) – Axis to use for reduction.
Returns:: The resulting image with size 1 in the reduction axis.
Return type:: HSImage

mul(rhs)¶

Multiply by an image or scalar to this image.

If the operand is a scalar, the operation is right scalar multiplication. If it is an image, the operation is elementwise multiplication with optional broadcasting.

Broadcasting is used for the operand if it is not of the same shape as the base image. Broadcasting uses the ndarray/numpy broadcasting rules.

Parameters:: rhs (HSImage | int | float) – Operand. Will possibly be broadcast to the base image shape.
Returns:: A new image. The shape is the same as the base image.
Return type:: HSImage

mul_left(lhs)¶

Perform left scalar “multiplication”.

Parameters:: lhs (int | float) – The left operand.
Returns:: A new image. The shape is the same as the base image.
Trype:: HSImage

nan_to_num(num, /)¶: Nan to Num

resolve()¶

Resolve the underlying operations to an in-memory representation.

Returns:: An in-memory image that can be efficiently accessed.
Return type:: HSImage

resolve_iter()¶

select(indices, /)¶

Select a spatial subset of spectral samples.

Useful for random samples - not efficient for contiguous access.

Parameters:: indices (Union[ndarray, list[list], list[tuple]]) – Coordinates to sample in Nx2 format, where N is the number of coordinates. The numbers must be integers.
Returns:: The samples as a Lx1xB image where L=len(indices) and B is the number of bands in the input image. The output is always flattened in this manner.
Return type:: HSImage

select_mask(mask, /)¶

Select a spatial subset of spectral samples using a mask array.

Useful for random samples - not efficient for contiguous access.

Parameters:: indices (Union[ndarray, list[list], list[tuple]]) – Coordinates to sample in Nx2 format, where N is the number of coordinates. The numbers must be integers.
Returns:: The samples as a Lx1xB image where L=len(indices) and B is the number of bands in the input image. The output is always flattened in this manner.
Return type:: HSImage

slice(slices)¶

Lazily index the image.

This method returns a new image that has been sliced according to the parameters. Note that this is a lazy operation which means that the actual slicing is only performed when the values are accessed or the image is resolved to memory.

Parameters:: slices (tuple[slice, slice, slice]) – Each slice must be a proper slice (i.e. a range of values) since the output image is always three-dimensional.
Returns:: The sliced image.
Type:: HSImage

std_axis(axis, /)¶

Calculate the standard deviation over the specified axis.

Parameters:: axis (Axis) – Axis to use for reduction.
Returns:: The resulting image with size 1 in the reduction axis.
Return type:: HSImage

stream()¶

Start a new Stream.

Returns:: A new stream object.
Return type:: Stream

sub(rhs)¶

Subtract an image or scalar from this image.

If the operand is a scalar, the operation is right scalar subtraction. If it is an image, the operation is elementwise subtraction with optional broadcasting.

Broadcasting is used for the operand if it is not of the same shape as the base image. Broadcasting uses the ndarray/numpy broadcasting rules.

Parameters:: rhs (HSImage | int | float) – Operand. Will possibly be broadcast to the base image shape.
Returns:: A new image. The shape is the same as the base image.
Return type:: HSImage

sub_left(lhs)¶

Perform left scalar “subtraction”.

Parameters:: lhs (int | float) – The left operand.
Returns:: A new image. The shape is the same as the base image.
Trype:: HSImage

sum_axis(axis, /)¶

Calculate the sum over the specified axis.

Parameters:: axis (Axis) – Axis to use for reduction.
Returns:: The resulting image with size 1 in the reduction axis.
Return type:: HSImage

to_interleave(interleave, block_size=Ellipsis, /)¶

Efficiently change the interleave format using buffering.

Parameters:: interleave (hsi.Interleave) – The target interleave.
Returns:: A new lazy image with the interleave change operation added.
Return type:: HSImage

to_numpy()¶

Convert the image to NumPy.

If the image is defined as a series of calculations, they are naturally resolved when this method is called.

Returns:: The datacube in the image’s interleave format.
Return type:: np.ndarray

to_numpy_with_interleave(interleave)¶

Convert the image to NumPy with the specified interleave format.

If the image is defined as a series of calculations, they are naturally resolved when this method is called.

Parameters:: interleave (Interleave) – Desired interleave format.
Returns:: The datacube in the specified interleave format.
Return type:: np.ndarray

to_numpy_with_permute(interleave)¶

Convert the image to NumPy with the specified interleave format without moving the data.

This method is more memory efficient than to_numpy_with_interleave but may lead to less efficient access from NumPy.

If the image is defined as a series of calculations, they are naturally resolved when this method is called.

Parameters:: interleave (Interleave) – Desired interleave format.
Returns:: The datacube in the specified interleave format.
Return type:: np.ndarray

ufunc(func)¶

Apply generic Python function on a plane-by-plane basis.

This method is a very primitive way for Python code to be integrated into the library. The provided function must take a single 2d array as input and return a 2d array as output.

The function must produce the same output size for all inputs of the same size! But it does not have to be the same as the input size. This is because all the returned planes must be able to be stacked into a 3d cube again at some point.

The method is applied by the library on a plane-by-plane basis in the cube. The ordering depends on the interleave, so this means that the function will have to take this into account if it is important. For BSQ files, each plane will be a band, for BIL/BIP, each plane will be a line.

Parameters:: func (Callable[[ndarray], ndarray]) – A Python function that takes and returns a 2d NumPy array. The size must be the same for all inputs of a specific size.

var_axis(axis, /)¶

Calculate the variance over the specified axis.

Parameters:: axis (Axis) – Axis to use for reduction.
Returns:: The resulting image with size 1 in the reduction axis.
Return type:: HSImage

with_header(header, /)¶

Attach a new header to the image. This method can be dangerous to use, since the new header isn’t checked for consistency.

Parameters:: header (HSIHeader) – New header.
Returns:: The image with the new header.
Return type:: HSImage

header¶

Return type:: HSIHeader

shape¶

Get the shape of the image.

Return type:: Shape