Image¶

class qtec_hv_sdk.Image¶

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:

Image

static from_numpy_with_meta(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 (ImageMeta) – The interleave format to use for the image.

Returns:

An in-memory image that can be efficiently accessed.

Return type:

Image

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 (Image | 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:: Image

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

as_dtype(dtype, /)¶

Convert the image to the specified type.

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

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:

Image

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:

Image

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 (Image | 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:: Image

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:

Image

ensure_dtype(dtype)¶

Efficiently convert to the target dtype if necessary.

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

filter(kernel, interleave, mode, block_size)¶

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:: Image

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 (Image | 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:: Image

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

parents()¶

resolve()¶

Resolve the underlying operations to an in-memory representation.

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

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:: Image

Example:

indices = [(200, 205), (200, 206)]
out = img.select(indices)
array = out.plane_axis(0, hsi.samples)

select_bands(bands, /)¶

Select a subset of bands from the image.

The output bands appear in the order specified by bands. Indices may be repeated to duplicate a band, and the resulting image has length len(bands) along the bands axis.

Parameters:: bands (list[int]) – Indices of the bands to select.
Returns:: A new image containing only the selected bands.
Return type:: Image

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:: Image

select_mask_from_descriptor(descriptor, /)¶

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:: Image

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:: Image

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 (Image | 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:: Image

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:: Image

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:: Image

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, slice_transform=None)¶

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[[hsi.FrameMeta, 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.
slice_transform (Callable[[tuple[slice, slice]], tuple[slice, slice]] | None) – Optional callable mapping the requested 2d output plane slice to the 2d input plane slice to fetch from the parent. Both are (slice, slice) tuples in interleave-aligned plane-axis order. When provided, func is called with the requested output plane slice as a third argument and is responsible for trimming its output to match. This allows emulating operations such as mean_axis or SNV that require the full extent of an axis regardless of the requested output slice.

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:: Image

with_meta(header, /)¶

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

Parameters:: meta (ImageMeta) – New meta.
Returns:: The image with the new metadata.
Return type:: Image

meta¶

Return type:: ImageMeta

shape¶

Get the shape of the image.

Return type:: Shape

uuid¶

Deterministic structural UUID identifying this node in the computation graph.

Two pipelines built from identical operations over structurally identical sources share the same UUID across processes and threads. Returned as a hyphenated string.