Module: search#

class kbmod.search.DebugTimer#

Bases: pybind11_object

A simple timer used for consistent outputing of timing results in verbose mode. Timer automatically starts when it is created.

Parameters:

namestr: The name string of the timer. Used for ouput.
verbosebool: Output the timing information to the standard output.

Methods

`read`(self)	Read the timer duration as decimal seconds.
`start`(self)	Start (or restart) the timer.
`stop`(self)	Stop the timer.

read(self: kbmod.search.DebugTimer) → float#

Read the timer duration as decimal seconds.

Returns:

durationfloat: The duration of the timer.

start(self: kbmod.search.DebugTimer) → None#: Start (or restart) the timer. If verbose=True, the object outputs a message.

stop(self: kbmod.search.DebugTimer) → None#: Stop the timer. If verbose=True, the object outputs the duration.

class kbmod.search.ImageStack#

Bases: pybind11_object

A class for storing a list of LayeredImages at different times.

Notes

The images are not required to be in sorted time order, but the first image is used for t=0.0 when computing zeroed times (which might make some times negative).

Attributes:

on_gpu: Indicates whether a copy of the images are stored on GPU.

Methods

`append_image`(self, img[, force_move])	Appends a single LayeredImage to the back of the ImageStack.
`build_zeroed_times`(self)	Construct an array of time differentials between each image in the stack and the first image.
`clear_from_gpu`(self)	Frees both the time and image data from the GPU.
`copy_to_gpu`(self)	Make a copy of the image and time data on the GPU.
`get_height`(self)	Returns the height of the images in pixels.
`get_images`(self)	Returns a reference to the vector of LayeredImages.
`get_npixels`(self)	Returns the number of pixels per image.
`get_obstime`(self, arg0)	Returns a single image's observation time in MJD.
`get_single_image`(self, arg0)	Returns a single LayeredImage for a given index.
`get_total_pixels`(self)	Returns the total number of pixels in all the images.
`get_width`(self)	Returns the width of the images in pixels.
`get_zeroed_time`(self, arg0)	Returns a single image's observation time relative to that of the first image.
`img_count`(self)	Returns the number of images in the stack.
`set_single_image`(self, index, img[, force_move])	Sets a single LayeredImage for at a given index.
`sort_by_time`(self)	Sort the images in the ImageStack by their time.

append_image(self: kbmod.search.ImageStack, img: kbmod.search.LayeredImage, force_move: bool = False) → None#

Appends a single LayeredImage to the back of the ImageStack.

Parameters:

imgLayeredImage: The new image.
force_movebool: Use move semantics. The input layered image is destroyed to avoid a copy of the LayeredImage.

Raises:

Raises a RuntimeError if the input image is the wrong size or the data
is currently on GPU.

build_zeroed_times(self: kbmod.search.ImageStack) → list[float]#

Construct an array of time differentials between each image in the stack and the first image. This can return negative times if the images are not sorted by time.

zeroed_time[i] = time[i] - time[0]

Returns:

zeroed_timeslist: A list of times starting at 0.0.

clear_from_gpu(self: kbmod.search.ImageStack) → None#: Frees both the time and image data from the GPU.

copy_to_gpu(self: kbmod.search.ImageStack) → None#: Make a copy of the image and time data on the GPU. The image data is stored as a single linear vector of floats where the value of pixel (i, j) in the image at time t is at: index = t * width * height + i * width + j

get_height(self: kbmod.search.ImageStack) → int#

Returns the height of the images in pixels.

Returns:

npixelsint: The height of each image in pixels.

get_images(self: kbmod.search.ImageStack) → list[kbmod.search.LayeredImage]#

Returns a reference to the vector of LayeredImages.

Returns:

imageslist: The reference to the vector of LayeredImages.

get_npixels(self: kbmod.search.ImageStack) → int#

Returns the number of pixels per image.

Returns:

npixelsint: The number of pixels per image.

get_obstime(self: kbmod.search.ImageStack, arg0: SupportsInt) → float#

Returns a single image’s observation time in MJD.

Parameters:

indexint: The index of the LayeredImage to retrieve.

Returns:

timedouble: The observation time (in UTC MJD).

Raises:

Raises a IndexError if the index is out of bounds.

get_single_image(self: kbmod.search.ImageStack, arg0: SupportsInt) → kbmod.search.LayeredImage#

Returns a single LayeredImage for a given index.

Parameters:

indexint: The index of the LayeredImage to retrieve.

Returns:

LayeredImage

Raises:

Raises a IndexError if the index is out of bounds.

get_total_pixels(self: kbmod.search.ImageStack) → int#

Returns the total number of pixels in all the images.

Returns:

npixelsint: The total number of pixels over all images.

get_width(self: kbmod.search.ImageStack) → int#

Returns the width of the images in pixels.

Returns:

npixelsint: The width of each image in pixels.

get_zeroed_time(self: kbmod.search.ImageStack, arg0: SupportsInt) → float#

Returns a single image’s observation time relative to that of the first image. This can return negative times if the images are not sorted by time.

zeroed_time[i] = time[i] - time[0]

Parameters:

indexint: The index of the LayeredImage to retrieve.

Returns:

timedouble: The zeroed observation time (in days).

Raises:

Raises a IndexError if the index is out of bounds.

img_count(self: kbmod.search.ImageStack) → int#

Returns the number of images in the stack.

Returns:

img_countint: The number of images in the stack.

property on_gpu#

Indicates whether a copy of the images are stored on GPU.

Returns:

on_gpubool: Indicates whether a copy of the images are stored on GPU.

set_single_image(self: kbmod.search.ImageStack, index: SupportsInt, img: kbmod.search.LayeredImage, force_move: bool = False) → None#

Sets a single LayeredImage for at a given index.

Parameters:

indexint: The index of the LayeredImage to set.
imgLayeredImage: The new image.
force_movebool: Use move semantics. The input layered image is destroyed to avoid a copy of the LayeredImage.

Raises:

Raises a IndexError if the index is out of bounds.
Raises a RuntimeError if the input image is the wrong size or the data
is currently on GPU.

sort_by_time(self: kbmod.search.ImageStack) → None#

Sort the images in the ImageStack by their time.

Raises:

Raises a RuntimeError if the input image is the data is currently on GPU.

class kbmod.search.Index#

Bases: pybind11_object

Array index.

Index can be compared to tuples and cast to a NumPy structured array. Index will cast non-int types into an integer without rounding, i.e. without applying floor or ceil to round the value to the nearest integer.

Parameters:

iint: Row index.
jint: Column index.

Attributes:

i
j

Methods

to_yaml(self)

Returns a single YAML record.

to_yaml(self: kbmod.search.Index) → str#: Returns a single YAML record.

class kbmod.search.LayeredImage#

Bases: pybind11_object

Creates a layered_image out of individual RawImage layers.

Parameters:

sciRawImage: The RawImage for the science layer.
varRawImage: The RawImage for the cariance layer.
mskRawImage: The RawImage for the mask layer.
psfnumpy.ndarray: The kernel of the PSF.
obstimefloat: The time of the image (in UTC MJD).

Raises:

RuntimeError:: If the science, variance and mask are not the same size.

Methods

`apply_mask`(self, arg0)	Applies the mask layer to each of the science and variance layers by checking whether the pixel in the mask layer is 0 (no masking) or non-zero (masked).
`binarize_mask`(self, arg0)	Convert the bitmask of flags into a single binary value of 1 for pixels that match one of the flags to use and 0 otherwise.
`contains`(args, *kwargs)	Overloaded function.
`convolve_given_psf`(self, arg0)	Convolves a given PSF with the science and variance layers (uses the PSF-squared for the variance).
`convolve_psf`(self)	Convolves the PSF stored within the LayeredImage with the science and variance layers (uses the PSF-squared for the variance).
`generate_phi_image`(self)	Generates the full phi image where the value of each pixel p in the resulting image is 1.0 / variance[p].
`generate_psi_image`(self)	Generates the full psi image where the value of each pixel p in the resulting image is science[p] / variance[p].
`get_height`(self)	Returns the image's height in pixels.
`get_mask`(self)	Returns the mask layer RawImage.
`get_npixels`(self)	Returns the image's total number of pixels.
`get_obstime`(self)	Get the image's observation time in UTC MJD.
`get_psf`(self)	Returns the PSF kernel.
`get_science`(self)	Returns the science layer RawImage.
`get_science_pixel`(args, *kwargs)	Overloaded function.
`get_variance`(self)	Returns the variance layer RawImage.
`get_variance_pixel`(args, *kwargs)	Overloaded function.
`get_width`(self)	Returns the image's width in pixels.
`mask_pixel`(args, *kwargs)	Overloaded function.
`science_pixel_has_data`(args, *kwargs)	Overloaded function.
`set_mask`(self, arg0)	Returns the mask layer RawImage.
`set_obstime`(self, arg0)	Set the image's observation time in UTC MJD.
`set_psf`(self, arg0)	Sets the PSF kernel.
`set_science`(self, arg0)	Returns the science layer RawImage.
`set_variance`(self, arg0)	Returns the science layer RawImage.

apply_mask(self: kbmod.search.LayeredImage, arg0: SupportsInt) → None#: Applies the mask layer to each of the science and variance layers by checking whether the pixel in the mask layer is 0 (no masking) or non-zero (masked). Applies all flags. To use a subset of flags call binarize_mask() first.

binarize_mask(self: kbmod.search.LayeredImage, arg0: SupportsInt) → None#

Convert the bitmask of flags into a single binary value of 1 for pixels that match one of the flags to use and 0 otherwise. Modifies the mask layer in-place. Used to select which masking flags are applied.

Note: This is a no-op for masks that are already binary and it is safe to call this function multiple times.

Parameters:

flags_to_useint: The bit mask of mask flags to keep.

contains(*args, **kwargs)#

Overloaded function.

contains(self: kbmod.search.LayeredImage, arg0: kbmod.search.Index) -> bool

Returns a Boolean indicating whether the image contains the given coordinates.

Parameters:

iint: Row index.
jint: Col index.

Returns:

resultbool: A Boolean indicating whether the image contains the given coordinates.

contains(self: kbmod.search.LayeredImage, arg0: typing.SupportsInt, arg1: typing.SupportsInt) -> bool

convolve_given_psf(self: kbmod.search.LayeredImage, arg0: Annotated[numpy.typing.ArrayLike, numpy.float32, '[m, n]']) → None#

Convolves a given PSF with the science and variance layers (uses the PSF-squared for the variance). Modifies the layers in place.

Parameters:

psfPSF: The PSF to use.

convolve_psf(self: kbmod.search.LayeredImage) → None#: Convolves the PSF stored within the LayeredImage with the science and variance layers (uses the PSF-squared for the variance). Modifies the layers in place.

generate_phi_image(self: kbmod.search.LayeredImage) → kbmod.search.RawImage#

Generates the full phi image where the value of each pixel p in the resulting image is 1.0 / variance[p]. To handle masked bits apply_mask() must be called before the phi image is generated. Otherwise, all pixels are used. Convolves the resulting image with the PSF.

Returns:

resultkbmod.RawImage: A RawImage of the same dimensions as the LayeredImage.

generate_psi_image(self: kbmod.search.LayeredImage) → kbmod.search.RawImage#

Generates the full psi image where the value of each pixel p in the resulting image is science[p] / variance[p]. To handle masked bits apply_mask() must be called before the psi image is generated. Otherwise, all pixels are used. Convolves the resulting image with the PSF.

Returns:

resultkbmod.RawImage: A RawImage of the same dimensions as the LayeredImage.

get_height(self: kbmod.search.LayeredImage) → int#: Returns the image’s height in pixels.

get_mask(self: kbmod.search.LayeredImage) → kbmod.search.RawImage#: Returns the mask layer RawImage.

get_npixels(self: kbmod.search.LayeredImage) → int#: Returns the image’s total number of pixels.

get_obstime(self: kbmod.search.LayeredImage) → float#: Get the image’s observation time in UTC MJD.

get_psf(self: kbmod.search.LayeredImage) → Annotated[numpy.typing.NDArray[numpy.float32], '[m, n]']#: Returns the PSF kernel.

get_science(self: kbmod.search.LayeredImage) → kbmod.search.RawImage#: Returns the science layer RawImage.

get_science_pixel(*args, **kwargs)#

Overloaded function.

get_science_pixel(self: kbmod.search.LayeredImage, arg0: kbmod.search.Index) -> float

Get the science pixel value at given index, checking the mask layer. Returns NO_DATA if any of the mask bits are set.

Parameters:

iint: Row index.
jint: Col index.

Returns:

valuefloat: Pixel value.

get_science_pixel(self: kbmod.search.LayeredImage, arg0: typing.SupportsInt, arg1: typing.SupportsInt) -> float

get_variance(self: kbmod.search.LayeredImage) → kbmod.search.RawImage#: Returns the variance layer RawImage.

get_variance_pixel(*args, **kwargs)#

Overloaded function.

get_variance_pixel(self: kbmod.search.LayeredImage, arg0: kbmod.search.Index) -> float

Get the variance pixel value at given index, checking the mask layer. Returns NO_DATA if any of the mask bits are set.

Parameters:

iint: Row index.
jint: Col index.

Returns:

valuefloat: Pixel value.

get_variance_pixel(self: kbmod.search.LayeredImage, arg0: typing.SupportsInt, arg1: typing.SupportsInt) -> float

get_width(self: kbmod.search.LayeredImage) → int#: Returns the image’s width in pixels.

mask_pixel(*args, **kwargs)#

Overloaded function.

mask_pixel(self: kbmod.search.LayeredImage, arg0: kbmod.search.Index) -> None

Apply masking to a single pixel. Applies to all three layers so that it can be used before or after apply_mask().

Parameters:

iint

Row index.

jint: Col index.

2. mask_pixel(self: kbmod.search.LayeredImage, arg0: typing.SupportsInt, arg1: typing.SupportsInt) -> None

science_pixel_has_data(*args, **kwargs)#

Overloaded function.

science_pixel_has_data(self: kbmod.search.LayeredImage, arg0: kbmod.search.Index) -> bool

Checks whether the science pixel has valid data by checking both the value in the science and mask layers.

Parameters:

iint: Row index.
jint: Col index.

Returns:

valuebool: Whether the science pixel has data.

science_pixel_has_data(self: kbmod.search.LayeredImage, arg0: typing.SupportsInt, arg1: typing.SupportsInt) -> bool

set_mask(self: kbmod.search.LayeredImage, arg0: kbmod.search.RawImage) → None#: Returns the mask layer RawImage.

set_obstime(self: kbmod.search.LayeredImage, arg0: SupportsFloat) → None#: Set the image’s observation time in UTC MJD.

set_psf(self: kbmod.search.LayeredImage, arg0: Annotated[numpy.typing.ArrayLike, numpy.float32, '[m, n]']) → None#: Sets the PSF kernel.

set_science(self: kbmod.search.LayeredImage, arg0: kbmod.search.RawImage) → None#: Returns the science layer RawImage.

set_variance(self: kbmod.search.LayeredImage, arg0: kbmod.search.RawImage) → None#: Returns the science layer RawImage.

class kbmod.search.Point#

Bases: pybind11_object

A point in Cartesian plane.

Point can be compared to tuples and cast to a NumPy structured array.

Parameters:

xfloat: Row index.
yfloat: Column index.

Attributes:

x
y

Methods

`to_index`(self)	Returns the Index this point is located in.
`to_yaml`(self)	Returns a single YAML record.

to_index(self: kbmod.search.Point) → kbmod.search.Index#: Returns the Index this point is located in.

to_yaml(self: kbmod.search.Point) → str#: Returns a single YAML record.

class kbmod.search.PsiPhi#

Bases: pybind11_object

A named tuple for psi and phi values.

Attributes:

psifloat: The psi value at a pixel.
phifloat: The phi value at a pixel.

class kbmod.search.PsiPhiArray#

Bases: pybind11_object

An encoded array of Psi and Phi values along with their meta data. This object supports automatic encoding of the psi/phi values (into float, uint8, or uint16) as well as the transfer of data to the GPU.

Attributes:

block_size: The size of a single entry in bytes.
cpu_array_allocated: A Boolean indicating whether the cpu data (psi/phi) array exists.
gpu_array_allocated: A Boolean indicating whether the gpu data (psi/phi) array exists.
height: The image height in pixels.
num_bytes: The target number of bytes to use for encoding the data (1 for uint8, 2 for uint16, or 4 for float32).
num_entries: The number of array entries (width x height x num_images).
num_times: The number of times.
on_gpu: A Boolean indicating whether a copy of the data is on the GPU.
phi_max_val: The maximum value of phi used in the scaling computations.
phi_min_val: The minimum value of phi used in the scaling computations.
phi_scale: The scaling parameter for phi.
pixels_per_image: The number of pixels per each image (width x height).
psi_max_val: The maximum value of psi used in the scaling computations.
psi_min_val: The minimum value of psi used in the scaling computations.
psi_scale: The scaling parameter for psi.
total_array_size: The size of the array in bytes.
width: The image width in pixels.

Methods

`clear`(self)	Clear all data and free the arrays.
`clear_from_gpu`(self)	Free the image and time data from the GPU memory.
`move_to_gpu`(self)	Move the image and time data to the GPU.
`read_psi_phi`(self, arg0, arg1, arg2)	Read a PsiPhi value from the CPU array.
`read_time`(self, arg0)	Read a zeroed time value from the CPU array.
`set_meta_data`(self, arg0, arg1, arg2, arg3)	Set the meta data for the array.
`set_time_array`(self, arg0)	Set the zeroed times.

property block_size#: The size of a single entry in bytes.

clear(self: kbmod.search.PsiPhiArray) → None#: Clear all data and free the arrays.

clear_from_gpu(self: kbmod.search.PsiPhiArray) → None#

Free the image and time data from the GPU memory. Does not copy the data back to the CPU.

Raises:

Raises a RuntimeError the data or settings are invalid.

property cpu_array_allocated#: A Boolean indicating whether the cpu data (psi/phi) array exists.

property gpu_array_allocated#: A Boolean indicating whether the gpu data (psi/phi) array exists.

property height#: The image height in pixels.

move_to_gpu(self: kbmod.search.PsiPhiArray) → None#

Move the image and time data to the GPU. Allocates space and copies the data.

Raises:

Raises a RuntimeError if the data or settings are invalid.

property num_bytes#: The target number of bytes to use for encoding the data (1 for uint8, 2 for uint16, or 4 for float32). Might differ from actual number of bytes (block_size).

property num_entries#: The number of array entries (width x height x num_images).

property num_times#: The number of times. Equivalent to the number of images stored.

property on_gpu#: A Boolean indicating whether a copy of the data is on the GPU.

property phi_max_val#: The maximum value of phi used in the scaling computations.

property phi_min_val#: The minimum value of phi used in the scaling computations.

property phi_scale#: The scaling parameter for phi.

property pixels_per_image#: The number of pixels per each image (width x height).

property psi_max_val#: The maximum value of psi used in the scaling computations.

property psi_min_val#: The minimum value of psi used in the scaling computations.

property psi_scale#: The scaling parameter for psi.

read_psi_phi(self: kbmod.search.PsiPhiArray, arg0: SupportsInt, arg1: SupportsInt, arg2: SupportsInt) → kbmod.search.PsiPhi#

Read a PsiPhi value from the CPU array. Performs automatic decoding of compressed data and returns the value as a float.

Parameters:

timeint: The timestep to read.
rowint: The row in the image (y-dimension)
colint: The column in the image (x-dimension)

Returns:

PsiPhi: The pixel values.

read_time(self: kbmod.search.PsiPhiArray, arg0: SupportsInt) → float#

Read a zeroed time value from the CPU array.

Parameters:

timeint: The timestep to read.

Returns:

float: The time.

set_meta_data(self: kbmod.search.PsiPhiArray, arg0: SupportsInt, arg1: SupportsInt, arg2: SupportsInt, arg3: SupportsInt) → None#

Set the meta data for the array. Automatically called by fill_psi_phi_array().

Parameters:

new_num_bytesint: The type of encoding to use (1, 2, or 4).
new_num_timesint: The number of time steps in the data.
new_heightint: The height of each image in pixels.
new_widthint: The width of each image in pixels.

set_time_array(self: kbmod.search.PsiPhiArray, arg0: list[SupportsFloat]) → None#

Set the zeroed times.

Parameters:

timeslist: A list of float with zeroed times.

property total_array_size#: The size of the array in bytes.

property width#: The image width in pixels.

class kbmod.search.RawImage#

Bases: pybind11_object

Image and the time it was observed at.

Instantiated from an image or from image dimensions and and a value (which defaults to zero).

Parameters:

imagenumpy.array, optional: Image, row-major a 2D array. The array must be of dtype numpy.single.
widthint, optional: Width of the image in pixels.
heightint, optional: Height of the image in pixels.
valuefloat, optional: When instantiated from dimensions, value that fills the array. Default is 0.

Notes

RawImage is internally represented by an Eigen Matrix object that uses float type. Because of this the given numpy array must be of np.single dtype. This is on purpose since memory on a GPU comes at a premium. Tests determined that loss of precision does not greatly affect the search.

Note also that KBMOD uses (width, height) convention is opposite to the NumPy’ array.shape convention which uses (row, col). KBMOD also distinguishes between a pair of coordinates in Cartesian plane, i.e. a point, which, usually expressed with the (x, y) convention and a pair of values representing indices to a 2D matrix, usually expressed with the (i, j) convention. Pixel accessing or setting methods of RawImage, such as get_pixel, use the indexing convention. This matches NumPy convention. Other methods, such as add_fake_object, however, use the (x, y) convention which is the reversed NumPy convention. Refer to individual methods signature and docstring to see which one they use.

Examples

>>> from kbmod.search import RawImage
>>> import numpy as np
>>> ri = RawImage()
>>> ri = RawImage(w=2, h=3, value=1)
>>> ri.image
array([[1., 1.],
     [1., 1.],
     [1., 1.]], dtype=float32)
>>> ri = RawImage(np.zeros((2, 3), dtype=np.single), 10)
>>> ri.image
array([[0., 0., 0.],
     [0., 0., 0.]], dtype=float32)

Attributes:

heightint: Image height, in pixels.
widthint: Image width, in pixels.
npixelsint: Number of pixels in the image, equivalent to width*height.
imagenp.array[np,single]: Image array.

Methods

`apply_mask`(self, arg0, arg1)	Applies a mask to the RawImage by comparing the given bit vector with the values in the mask layer and marking pixels `NO_DATA`.
`compute_bounds`(self[, strict_checks])	Returns min and max pixel values, ignoring the masked pixels.
`contains_index`(args, *kwargs)	Overloaded function.
`contains_point`(args, *kwargs)	Overloaded function.
`convolve_cpu`(self, arg0)	Convolve the image with a PSF.
`convolve_gpu`(self, arg0)	Convolve the image with a PSF on the GPU.
`create_stamp`(args, *kwargs)	Overloaded function.
`get_pixel`(args, *kwargs)	Overloaded function.
`mask_pixel`(args, *kwargs)	Overloaded function.
`pixel_has_data`(args, *kwargs)	Overloaded function.
`replace_masked_values`(self[, value])	Replace the masked values in an image with a given value.
`set_all`(self, arg0)	Sets all image pixel values to the given value.
`set_pixel`(args, *kwargs)	Overloaded function.

apply_mask(self: kbmod.search.RawImage, arg0: SupportsInt, arg1: kbmod.search.RawImage) → None#

Applies a mask to the RawImage by comparing the given bit vector with the values in the mask layer and marking pixels NO_DATA.

Modifies the image in-place.

Parameters:

flagint: The bit mask of mask flags to use. Use 0xFFFFFF to apply all flags.
maskRawImage: The image of pixel mask values.

compute_bounds(self: kbmod.search.RawImage, strict_checks: bool = True) → Annotated[list[float], FixedSize(2)]#

Returns min and max pixel values, ignoring the masked pixels.

Parameters:

strict_checksbool: If True and none of the pixels contain data, then raises an RuntimeError. If False and none of the pixels contain data, returns (0.0, 0.0).

Returns:

boundstuple: A (min, max) tuple.

contains_index(*args, **kwargs)#

Overloaded function.

contains_index(self: kbmod.search.RawImage, arg0: kbmod.search.Index) -> bool

True if the given index falls within the image dimensions. Note that the x and y ordering is the inverse of contains_point().

Parameters:

iint: Row index (y position)
jint: Col index (x position)

Returns:

resultbool: True when point falls within the image dimensions.

contains_index(self: kbmod.search.RawImage, arg0: typing.SupportsInt, arg1: typing.SupportsInt) -> bool

contains_point(*args, **kwargs)#

Overloaded function.

contains_point(self: kbmod.search.RawImage, arg0: kbmod.search.Point) -> bool

True if the given point falls within the image dimensions. Note that the x and y ordering is the inverse of contains_index().

Parameters:

xfloat: The real valued x position (mapped to the matrix’s column).
yfloat: The real valued y position (mapped to the matrix’s row).

Returns:

resultbool: True when point falls within the image dimensions.

contains_point(self: kbmod.search.RawImage, arg0: typing.SupportsFloat, arg1: typing.SupportsFloat) -> bool

convolve_cpu(self: kbmod.search.RawImage, arg0: Annotated[numpy.typing.ArrayLike, numpy.float32, '[m, n]']) → None#

Convolve the image with a PSF.

Convolves in-place.

Parameters:

psfnumpy.ndarray: The kernel of the Point Spread Function.

convolve_gpu(self: kbmod.search.RawImage, arg0: Annotated[numpy.typing.ArrayLike, numpy.float32, '[m, n]']) → None#

Convolve the image with a PSF on the GPU.

Convolves in-place.

Parameters:

psfnumpy.ndarray: The kernel of the Point Spread Function.

create_stamp(*args, **kwargs)#

Overloaded function.

create_stamp(self: kbmod.search.RawImage, arg0: kbmod.search.Point, arg1: typing.SupportsInt, arg2: bool) -> kbmod.search.RawImage

Create an image stamp around a given region.

Parameters:

xfloat: The x value of the center of the stamp.
yfloat: The y value of the center of the stamp.
radiusint: The stamp radius. Width = 2*radius+1.
keep_no_databool: A Boolean indicating whether to preserve NO_DATA tags or to replace them with 0.0.

Returns:

RawImage: The stamp.

create_stamp(self: kbmod.search.RawImage, arg0: typing.SupportsFloat, arg1: typing.SupportsFloat, arg2: typing.SupportsInt, arg3: bool) -> kbmod.search.RawImage

get_pixel(*args, **kwargs)#

Overloaded function.

get_pixel(self: kbmod.search.RawImage, arg0: kbmod.search.Index) -> float

Get pixel at given index.

Parameters:

iint: Row index (y position)
jint: Col index (x position)

Returns:

valuefloat: Pixel value.

get_pixel(self: kbmod.search.RawImage, arg0: typing.SupportsInt, arg1: typing.SupportsInt) -> float

mask_pixel(*args, **kwargs)#

Overloaded function.

mask_pixel(self: kbmod.search.RawImage, arg0: kbmod.search.Index) -> None

Sets image pixel at an invalid value that indicates it is masked.

Parameters:

iint

Row index (y position)

jint: Col index (x position)

2. mask_pixel(self: kbmod.search.RawImage, arg0: typing.SupportsInt, arg1: typing.SupportsInt) -> None

pixel_has_data(*args, **kwargs)#

Overloaded function.

pixel_has_data(self: kbmod.search.RawImage, arg0: kbmod.search.Index) -> bool

True if the pixel at given index is not masked.

Parameters:

iint: Row index (y position)
jint: Col index (x position)

Returns:

has_databool: True when pixel is not masked, False otherwise.

pixel_has_data(self: kbmod.search.RawImage, arg0: typing.SupportsInt, arg1: typing.SupportsInt) -> bool

replace_masked_values(self: kbmod.search.RawImage, value: SupportsFloat = 0.0) → None#

Replace the masked values in an image with a given value.

Parameters:

valuefloat: The value to swap in. Default = 0.0.

set_all(self: kbmod.search.RawImage, arg0: SupportsFloat) → None#

Sets all image pixel values to the given value.

Parameters:

valuefloat: Value to set the pixels to.

set_pixel(*args, **kwargs)#

Overloaded function.

set_pixel(self: kbmod.search.RawImage, arg0: kbmod.search.Index, arg1: typing.SupportsFloat) -> None

Sets image pixel at given index to the given value.

Parameters:

iint

Row index (y position)

jint: Col index (x position)
valuefloat: Value to set the pixels to.

2. set_pixel(self: kbmod.search.RawImage, arg0: typing.SupportsInt, arg1: typing.SupportsInt, arg2: typing.SupportsFloat) -> None

class kbmod.search.Rectangle#

Bases: pybind11_object

A rectangular selection of an array.

The rectangle can also contain its corner origin Index with respect to a second reference point. Most commonly the corner of another, larger, rectangle - f.e. as is the case when selecting a stamp to copy from origin array and pasting the selection into a destination array.

Rectangles can be cast into NumPy structured arrays.

Parameters:

cornerIndex or tuple: Top left corner of the rectangle, in origin coordinates.
anchorIndex or tuple, optional: Top left corner of the rectangle, in destination coordinates.
widthint: Positive integer, width of the rectangle.
heightint: Positive integer, height of the rectangle.

Attributes:

iint: Row index of the corner.
jint: Column index of the corner.

Methods

to_yaml(self)

Returns a single YAML record.

to_yaml(self: kbmod.search.Rectangle) → str#: Returns a single YAML record.

class kbmod.search.StackSearch#

Bases: pybind11_object

The data and configuration needed for KBMOD’s core search. It is created using a reference to the ImageStack. The underlying ImageStack must exist for the life of the StackSearch object’s life.

Methods

`clear_psi_phi`(self)	Clear the pre-computed psi and phi data.
`compute_max_results`(self)	Compute the maximum number of results according to the x, y bounds and the results per pixel.
`disable_gpu_sigmag_filter`(self)	Turns off the on-GPU sigma-G filtering.
`enable_gpu_encoding`(self, arg0)	Set the encoding level for the data copied to the GPU.
`enable_gpu_sigmag_filter`(self, arg0, arg1, arg2)	Enable on-GPU sigma-G filtering.
`evaluate_single_trajectory`(self, arg0)	Performs the evaluation of a single Trajectory object.
`finish_search`(self)	Clears memory used for the batch search.
`get_image_height`(self)	Returns the height of the images in pixels.
`get_image_npixels`(self)	Returns the number of pixels for each image.
`get_image_width`(self)	Returns the width of the images in pixels.
`get_imagestack`(self)	Return the kb.ImageStack containing the data to search.
`get_num_images`(self)	Returns the number of images to process.
`get_number_total_results`(self)	Get the total number of saved results.
`get_phi_curves`(args, *kwargs)	Overloaded function.
`get_psi_curves`(args, *kwargs)	Overloaded function.
`get_results`(self, arg0, arg1)	Get a batch of cached results.
`prepare_psi_phi`(self)	Compute the cached psi and phi data.
`prepare_search`(self, arg0, arg1)	Prepare the search for a batch of trajectories.
`search_all`(self, arg0, arg1)	Perform the KBMOD search by evaluating a list of candidate trajectories at each starting pixel in the image.
`search_linear_trajectory`(self, arg0, arg1, ...)	Performs the evaluation of a linear trajectory in pixel space.
`search_single_batch`(self)	Perform a search on the given trajectories for the current batch.
`set_min_lh`(self, arg0)	Sets the minimum likelihood for valid result.
`set_min_obs`(self, arg0)	Sets the minimum number of observations for valid result.
`set_results`(self, arg0)	Set the cached results.
`set_results_per_pixel`(self, arg0)	Set the maximum number of results per pixel returns by a search.
`set_start_bounds_x`(self, arg0, arg1)	Set the starting and ending bounds in the x direction for a grid search.
`set_start_bounds_y`(self, arg0, arg1)	Set the starting and ending bounds in the y direction for a grid search.

clear_psi_phi(self: kbmod.search.StackSearch) → None#: Clear the pre-computed psi and phi data.

compute_max_results(self: kbmod.search.StackSearch) → int#

Compute the maximum number of results according to the x, y bounds and the results per pixel.

Returns:

max_resultsint: The maximum number of results that a search will return.

disable_gpu_sigmag_filter(self: kbmod.search.StackSearch) → None#: Turns off the on-GPU sigma-G filtering.

enable_gpu_encoding(self: kbmod.search.StackSearch, arg0: SupportsInt) → None#

Set the encoding level for the data copied to the GPU.: 1 = uint8 2 = uint16 4 or -1 = float

Parameters:

encode_num_bytesint: The number of bytes to use for encoding the data.

enable_gpu_sigmag_filter(self: kbmod.search.StackSearch, arg0: list[SupportsFloat], arg1: SupportsFloat, arg2: SupportsFloat) → None#

Enable on-GPU sigma-G filtering.

Parameters:

percentileslist: A length 2 list of percentiles (between 0.0 and 1.0). Example [0.25, 0.75].
sigmag_coefffloat: The sigma-G coefficient corresponding to the percentiles. This can be computed via SigmaGClipping.find_sigma_g_coeff().
min_lhfloat: The minimum likelihood for a result to be accepted.

Raises:

Raises a RunTimeError if invalid values are provided.

evaluate_single_trajectory(self: kbmod.search.StackSearch, arg0: search::Trajectory) → None#

Performs the evaluation of a single Trajectory object. Modifies the trajectory object in-place to add the statistics.

Parameters:

trjkb.Trajectory: The trjactory to evaluate.

Notes

Runs on the CPU, but requires CUDA compiler.

finish_search(self: kbmod.search.StackSearch) → None#

Clears memory used for the batch search.

This method should be called after a batch search is completed to ensure that any resources allocated during the search are properly freed.

get_image_height(self: kbmod.search.StackSearch) → int#: Returns the height of the images in pixels.

get_image_npixels(self: kbmod.search.StackSearch) → int#: Returns the number of pixels for each image.

get_image_width(self: kbmod.search.StackSearch) → int#: Returns the width of the images in pixels.

get_imagestack(self: kbmod.search.StackSearch) → kbmod.search.ImageStack#: Return the kb.ImageStack containing the data to search.

get_num_images(self: kbmod.search.StackSearch) → int#: Returns the number of images to process.

get_number_total_results(self: kbmod.search.StackSearch) → int#

Get the total number of saved results.

Returns:

resultint: The number of saved results.

get_phi_curves(*args, **kwargs)#

Overloaded function.

get_phi_curves(self: kbmod.search.StackSearch, arg0: search::Trajectory) -> list[float]

Return the time series of phi values for a given trajectory in pixel space.

Parameters:

trjkb.Trajectory or list of kb.Trajectory: The input trajectory or trajectories.

Returns:

resultlist of float or list of list of float: The phi values at each time step with NO_DATA replaced by 0.0.

get_phi_curves(self: kbmod.search.StackSearch, arg0: list[search::Trajectory]) -> list[list[float]]

get_psi_curves(*args, **kwargs)#

Overloaded function.

get_psi_curves(self: kbmod.search.StackSearch, arg0: search::Trajectory) -> list[float]

Return the time series of psi values for a given trajectory in pixel space.

Parameters:

trjkb.Trajectory or list of kb.Trajectory: The input trajectory or trajectories.

Returns:

resultlist of float or list of list of float: The psi values at each time step with NO_DATA replaced by 0.0.

get_psi_curves(self: kbmod.search.StackSearch, arg0: list[search::Trajectory]) -> list[list[float]]

get_results(self: kbmod.search.StackSearch, arg0: SupportsInt, arg1: SupportsInt) → list[search::Trajectory]#

Get a batch of cached results.

Parameters:

startint: The starting index of the results to retrieve. Returns an empty list if start is past the end of the cache.
countint: The maximum number of results to retrieve. Returns fewer results if there are not enough in the cache.

Returns:

resultsList: A list of Trajectory objects for the cached results.

Raises:

RunTimeError if start < 0 or count <= 0.

prepare_psi_phi(self: kbmod.search.StackSearch) → None#: Compute the cached psi and phi data.

prepare_search(self: kbmod.search.StackSearch, arg0: list[search::Trajectory], arg1: typing.SupportsInt) → None#

Prepare the search for a batch of trajectories.

Parameters:

search_listList: A list of Trajectory objects to search.
min_observationsint: The minimum number of observations for a trajectory to be considered.

search_all(self: kbmod.search.StackSearch, arg0: list[search::Trajectory], arg1: typing.SupportsInt) → None#

Perform the KBMOD search by evaluating a list of candidate trajectories at each starting pixel in the image. The results are stored in the StackSearch object and can be accessed with get_results().

Parameters:

search_listlist: A list of Trajectory objects where each trajectory is evaluated at each starting pixel.
min_observationsint: The minimum number of valid observations for a trajectory to be saved.

search_linear_trajectory(self: kbmod.search.StackSearch, arg0: SupportsInt, arg1: SupportsInt, arg2: SupportsFloat, arg3: SupportsFloat) → search::Trajectory#

Performs the evaluation of a linear trajectory in pixel space.

Parameters:

xshort: The starting x pixel of the trajectory.
yshort: The starting y pixel of the trajectory.
vxfloat: The x velocity of the trajectory in pixels per day.
vyfloat: The y velocity of the trajectory in pixels per day.

Returns:

resultkb.Trajectory: The trajectory object with statistics set.

Notes

Runs on the CPU, but requires CUDA compiler.

search_single_batch(self: kbmod.search.StackSearch) → list[search::Trajectory]#

Perform a search on the given trajectories for the current batch. Batch is defined by the parameters set set_start_bounds_x & set_start_bounds_y.

Returns:

resultsList: A list of Trajectory search results

set_min_lh(self: kbmod.search.StackSearch, arg0: SupportsFloat) → None#

Sets the minimum likelihood for valid result.

Parameters:

new_valuefloat: The minimum likelihood value for a trajectory to be returned.

set_min_obs(self: kbmod.search.StackSearch, arg0: SupportsInt) → None#

Sets the minimum number of observations for valid result.

Parameters:

new_valueint: The minimum number of valid observations for a trajectory to be returned.

set_results(self: kbmod.search.StackSearch, arg0: list[search::Trajectory]) → None#

Set the cached results. Used for testing.

Parameters:

new_resultsList: The list of results (Trajectory objects) to store.

set_results_per_pixel(self: kbmod.search.StackSearch, arg0: SupportsInt) → None#

Set the maximum number of results per pixel returns by a search.

Parameters:

new_valueint: The new number of results per pixel.

Raises:

Raises a RunTimeError if an invalid value is provided (new_value <= 0).

set_start_bounds_x(self: kbmod.search.StackSearch, arg0: SupportsInt, arg1: SupportsInt) → None#

Set the starting and ending bounds in the x direction for a grid search. The grid search will test all pixels [x_min, x_max).

Parameters:

x_minint: The inclusive lower bound of the search (in pixels).
x_maxint: The exclusive upper bound of the search (in pixels).

Raises:

Raises a RunTimeError if invalid bounds are provided (x_max > x_min).

set_start_bounds_y(self: kbmod.search.StackSearch, arg0: SupportsInt, arg1: SupportsInt) → None#

Set the starting and ending bounds in the y direction for a grid search. The grid search will test all pixels [y_min, y_max).

Parameters:

y_minint: The inclusive lower bound of the search (in pixels).
y_maxint: The exclusive upper bound of the search (in pixels).

Raises:

Raises a RunTimeError if invalid bounds are provided (x_max > x_min).

class kbmod.search.StampParameters#

Bases: pybind11_object

Parameters for stamp generation and filtering.

Attributes:

radiusint: The stamp radius (in pixels)
stamp_typeStampType: The co-add method to use for co-added stamps. Must be one of STAMP_SUM, STAMP_MEAN, STAMP_MEDIAN, or STAMP_VAR_WEIGHTED.

class kbmod.search.StampType#

Bases: pybind11_object

Members:

STAMP_SUM

STAMP_MEAN

STAMP_MEDIAN

STAMP_VAR_WEIGHTED

Attributes:

name: name(self: object, /) -> str
value

property name#

class kbmod.search.Trajectory#

Bases: pybind11_object

A structure for holding basic information about potential results in the form of a linear trajectory in pixel space.

Attributes:

xfloat: x coordinate of the trajectory at first time step (in pixels)
yfloat: y coordinate of the trajectory at first time step (in pixels)
vxfloat: x component of the velocity, as projected on the image (in pixels per day)
vyfloat: y component of the velocity, as projected on the image (in pixels per day)
lhfloat: The computed likelihood of all (valid) points along the trajectory.
fluxfloat: The computed likelihood of all (valid) points along the trajectory.
obs_countint: The number of valid points along the trajectory.

Methods

`get_x_index`(self, arg0)	Returns the predicted x position of the trajectory as an integer (column) index.
`get_x_pos`(self, time[, centered])	Returns the predicted x position of the trajectory.
`get_y_index`(self, arg0)	Returns the predicted x position of the trajectory as an integer (row) index.
`get_y_pos`(self, time[, centered])	Returns the predicted y position of the trajectory.
`is_close`(self, arg0, arg1, arg2)	Checks whether a second Trajectory falls within given thresholds of closeness for pixel difference and velocity difference.

get_x_index(self: kbmod.search.Trajectory, arg0: SupportsFloat) → int#

Returns the predicted x position of the trajectory as an integer (column) index.

Parameters:

timefloat: A zero shifted time in days.

Returns:

int: The predicted column index.

get_x_pos(self: kbmod.search.Trajectory, time: SupportsFloat, centered: bool = True) → float#

Returns the predicted x position of the trajectory.

Parameters:

timefloat: A zero shifted time in days.
centeredbool: Shift the prediction to be at the center of the pixel (e.g. xp = x + vx * time + 0.5f). Default = True.

Returns:

float: The predicted x position (in pixels).

get_y_index(self: kbmod.search.Trajectory, arg0: SupportsFloat) → int#

Returns the predicted x position of the trajectory as an integer (row) index.

Parameters:

timefloat: A zero shifted time in days.

Returns:

int: The predicted row index.

get_y_pos(self: kbmod.search.Trajectory, time: SupportsFloat, centered: bool = True) → float#

Returns the predicted y position of the trajectory.

Parameters:

timefloat: A zero shifted time in days.
centeredbool: Shift the prediction to be at the center of the pixel (e.g. xp = x + vx * time + 0.5f). Default = True.

Returns:

float: The predicted y position (in pixels).

is_close(self: kbmod.search.Trajectory, arg0: kbmod.search.Trajectory, arg1: SupportsFloat, arg2: SupportsFloat) → bool#

Checks whether a second Trajectory falls within given thresholds of closeness for pixel difference and velocity difference.

Parameters:

trj_bTrajectory: The Trajectory to test.
pos_threshfloat: The maximum separation in each of the x and y dimension (in pixels).
vel_threshfloat: The maximum separation in each of the x and y velocities (in pixels/day).

Returns:

bool: Whether the two trajectories are close.

class kbmod.search.TrajectoryList#

Bases: pybind11_object

A list of trajectories that can be transferred between CPU or GPU.

Attributes:

on_gpu: Whether the data currently resides on the GPU (True) or CPU (False)

Methods

`get_batch`(self, arg0, arg1)	Return a batch of results.
`get_list`(self)	Return the full list of trajectories.
`get_size`(self)	Return the size of the list.
`get_trajectory`(self, arg0)	Get a reference trajectory from the list.
`move_to_cpu`(self)	Move the data from GPU to CPU.
`move_to_gpu`(self)	Move the data from CPU to GPU.
`resize`(self, arg0)	Forcibly resize the array.
`set_trajectories`(self, arg0)	Set an entire list of trajectories.
`set_trajectory`(self, arg0, arg1)	Set a trajectory in the list.
`sort_by_likelihood`(self)	Sort the data in order of decreasing likelihood.

get_batch(self: kbmod.search.TrajectoryList, arg0: SupportsInt, arg1: SupportsInt) → list[kbmod.search.Trajectory]#

Return a batch of results. The data must reside on the CPU.

Parameters:

startint: The starting index of the results to retrieve. Returns an empty list if start is past the end of the cache.
countint: The maximum number of results to retrieve. Returns fewer results if there are not enough in the cache.

Returns:

resultsList: A list of Trajectory objects for the cached results.

Raises:

RunTimeError if start < 0 or count <= 0 or if the data is on GPU.

get_list(self: kbmod.search.TrajectoryList) → list[kbmod.search.Trajectory]#

Return the full list of trajectories. The data must reside on the CPU.

Returns:

resultlist: The list of trajectories

Raises:

Raises a RuntimeError if the data currently resides on the GPU.

get_size(self: kbmod.search.TrajectoryList) → int#: Return the size of the list.

get_trajectory(self: kbmod.search.TrajectoryList, arg0: SupportsInt) → kbmod.search.Trajectory#

Get a reference trajectory from the list. The data must reside on the CPU.

Parameters:

indexint: The index of the entry.

Returns:

trjTrajectory: The corresponding Trajectory object.

Raises:

Raises a RuntimeError if the index is invalid or the data currently resides
on the GPU.

move_to_cpu(self: kbmod.search.TrajectoryList) → None#

Move the data from GPU to CPU. If the data is already on the CPU this is a no-op.

Raises:

Raises a RuntimeError if invalid state encountered.

move_to_gpu(self: kbmod.search.TrajectoryList) → None#

Move the data from CPU to GPU. If the data is already on the GPU this is a no-op.

Raises:

Raises a RuntimeError if invalid state encountered.

property on_gpu#: Whether the data currently resides on the GPU (True) or CPU (False)

resize(self: kbmod.search.TrajectoryList, arg0: SupportsInt) → None#

Forcibly resize the array. If the size is decreased, the extra entries are dropped from the back. If the size is increased, extra (blank) trajectories are added to the back.

The data must reside on the CPU.

Parameters:

new_sizeint: The new size of the list.

Raises:

RunTimeError if new_size < 0 or data is on GPU.

set_trajectories(self: kbmod.search.TrajectoryList, arg0: list[kbmod.search.Trajectory]) → None#

Set an entire list of trajectories. Resizes the array to match the given input. The data must reside on the CPU.

Parameters:

new_valueslist: A list of Trajectory objects.

Raises:

Raises a RuntimeError if the index is invalid or the data currently resides
on the GPU.

set_trajectory(self: kbmod.search.TrajectoryList, arg0: SupportsInt, arg1: kbmod.search.Trajectory) → None#

Set a trajectory in the list. The data must reside on the CPU.

Parameters:

indexint: The index of the entry.
new_valueTrajectory: The corresponding Trajectory object.

Raises:

Raises a RuntimeError if the index is invalid or the data currently resides
on the GPU.

sort_by_likelihood(self: kbmod.search.TrajectoryList) → None#

Sort the data in order of decreasing likelihood. The data must reside on the CPU.

Raises:

Raises a RuntimeError the data is on GPU.

kbmod.search.anchored_block(arg0: tuple[SupportsInt, SupportsInt], arg1: SupportsInt, arg2: tuple[SupportsInt, SupportsInt]) → kbmod.search.Rectangle#

Returns rectangle selection of an array centered on given coordinate.

Parameters:

idxtuple: Center of the rectangle selection, indices (row, col).
rint: Radius around the central index to select.
shapeint: Shape of the origin array.

Returns:

rectRectangle: Selected rectangle, such that the corner + width/height returns the desired array slice.

Examples

>>> img = numpy.arange(100).reshape(10, 10)
>>> rect = anchored_block((5, 5), 1, img.shape)
>>> rect
Rectangle(corner: (4, 4), anchor: (0, 0), width: 3, height: 3)
>>> stamp = img[rect.i:rect.i+rect.height, rect.j:rect.j+width]
>>> stamp
array([[44, 45, 46],
       [54, 55, 56],
       [64, 65, 66]])

By default, anchor is calculated such that it fits into a destination with a shape (2r+1, 2r+1), i.e. (rect.width, rect.height). Note the requested radius clips to the left and top of the array.

>>> dest = np.zeros((3, 3)) - 1
>>> rect = anchored_block((0, 0), 1, img.shape)
>>> dest[rect.anchor.i:, rect.anchor] = stamp
array([[-1., -1., -1.],
       [-1.,  0.,  1.],
       [-1., 10., 11.]])

kbmod.search.centered_range(arg0: SupportsInt, arg1: SupportsInt, arg2: SupportsInt) → tuple[int, int, int]#

Given a reference value and a radius around it, returns the range start, end and length that fit into the width of the interval.

The returned range is [val-r, val+r].

Parameters:

valint: Center of the returned range.
rint: Radius around the center to select.
widthint: Maximum allowed width of the interval.

Returns:

intervaltuple: The triplet (start, end, length) = [val-r, val+r, 2r+1] trimmed to fit within [0, width] range.

Examples

Interval of radius 1, centered on 5, i.e. [4, 5, 6]:

>>> centered_range(5, 1, 10)
(4, 6, 3)

Interval of radius 2, centered on 1, this time the allowed range [0, width] clips the returned range, i.e. [0, 1, 2, 3]

>>> centered_range(1, 2, 10)
(0, 3, 4)

kbmod.search.compute_scale_params_from_image_vect(arg0: list[kbmod.search.RawImage], arg1: SupportsInt) → Annotated[list[float], FixedSize(3)]#

kbmod.search.create_mean_image(arg0: list[kbmod.search.RawImage]) → kbmod.search.RawImage#

kbmod.search.create_median_image(arg0: list[kbmod.search.RawImage]) → kbmod.search.RawImage#

kbmod.search.create_stamps(arg0: kbmod.search.ImageStack, arg1: search::Trajectory, arg2: typing.SupportsInt, arg3: bool, arg4: list[bool]) → list[kbmod.search.RawImage]#

Create a vector of stamps centered on the predicted position of an Trajectory at different times.

Parameters:

stackImageStack: The stack of images to use.
trjTrajectory: The trajectory to project to each time.
radiusint: The stamp radius in pixels. The total stamp width = 2*radius+1.
keep_no_databool: A Boolean indicating whether to preserve NO_DATA tags or to replace them with 0.0.
use_indexlist of bool: A list (vector) of Booleans indicating whether or not to use each time step. An empty (size=0) vector will use all time steps.

Returns:

list of RawImage: The stamps.

kbmod.search.create_stamps_xy(arg0: kbmod.search.ImageStack, arg1: SupportsInt, arg2: list[SupportsInt], arg3: list[SupportsInt], arg4: list[SupportsInt]) → list[kbmod.search.RawImage]#

Create a vector of stamps centered on a list of x and y pixel positions.

Parameters:

stackImageStack: The stack of images to use.
radiusint: The stamp radius in pixels. The total stamp width = 2*radius+1.
xvalslist of int: The x-coordinate of the stamp center at each time.
yvalslist of int: The y-coordinate of the stamp center at each time.
image_indiceslist of int: A list of which time step to use for each coordinate. If empty, then uses all images in order.

Returns:

list of RawImage: The stamps.

kbmod.search.create_summed_image(arg0: list[kbmod.search.RawImage]) → kbmod.search.RawImage#

kbmod.search.create_variance_stamps(arg0: kbmod.search.ImageStack, arg1: search::Trajectory, arg2: typing.SupportsInt, arg3: list[bool]) → list[kbmod.search.RawImage]#

Create a vector of stamps from the variance layer centered on the predicted position of an Trajectory at different times.

Parameters:

stackImageStack: The stack of images to use.
trjTrajectory: The trajectory to project to each time.
radiusint: The stamp radius in pixels. The total stamp width = 2*radius+1.
use_indexlist of bool: A list (vector) of Booleans indicating whether or not to use each time step. An empty (size=0) vector will use all time steps.

Returns:

list of RawImage: The stamps.

kbmod.search.decode_uint_scalar(arg0: SupportsFloat, arg1: SupportsFloat, arg2: SupportsFloat) → float#

kbmod.search.encode_uint_scalar(arg0: SupportsFloat, arg1: SupportsFloat, arg2: SupportsFloat, arg3: SupportsFloat) → float#

kbmod.search.fill_psi_phi_array(arg0: kbmod.search.PsiPhiArray, arg1: SupportsInt, arg2: list[kbmod.search.RawImage], arg3: list[kbmod.search.RawImage], arg4: list[SupportsFloat]) → None#

Fill the PsiPhiArray from Psi and Phi images.

Parameters:

result_dataPsiPhiArray: The location to store the data.
num_bytesint: The type of encoding to use (1, 2, or 4).
psi_imgslist: A list of psi images.
phi_imgslist: A list of phi images.
zeroed_timeslist: A list of floating point times starting at zero.

Raises:

Raises a RuntimeError if invalid values are found in the psi or phi arrays.

kbmod.search.fill_psi_phi_array_from_image_stack(arg0: kbmod.search.PsiPhiArray, arg1: kbmod.search.ImageStack, arg2: SupportsInt) → None#

Fill the PsiPhiArray an ImageStack.

Parameters:

result_dataPsiPhiArray: The location to store the data.
num_bytesint: The type of encoding to use (1, 2, or 4).
stackImageStack: The stack of LayeredImages from which to build the psi and phi images.

Raises:

Raises a RuntimeError if invalid values are found.

kbmod.search.get_coadded_stamps(arg0: kbmod.search.ImageStack, arg1: list[search::Trajectory], arg2: list[list[bool]], arg3: search::StampParameters, arg4: bool) → list[kbmod.search.RawImage]#

Create a vector of co-added stamps centered on the predicted position of trajectories at different times.

Parameters:

stackImageStack: The stack of images to use.
trjlist of Trajectory: The list of trajectories to uses.
use_indexlist of list of bool: A list of lists (vectors) of Booleans indicating whether or not to use each time step. use_index[i][j] indicates whether we should use timestep j of trajectory i. An empty (size=0) list for any trajectory will use all time steps for that trajectory.
paramsStampParameters: The parameters for stamp generation, such as radius and co-add type.
use_gpubool: A Boolean indicating whether to do the co-adds on the CPU (False) or GPU (True).

Returns:

list of RawImage: The co-added stamps.

kbmod.search.get_gpu_free_memory() → int#: Return the GPUs free memory in bytes.

kbmod.search.get_gpu_total_memory() → int#: Return the GPUs total memory in bytes.

kbmod.search.get_mean_stamp(arg0: kbmod.search.ImageStack, arg1: search::Trajectory, arg2: typing.SupportsInt, arg3: list[bool]) → kbmod.search.RawImage#

Create the mean co-added stamp centered on the predicted position of an Trajectory at different times. Preserves NO_DATA tag.

Parameters:

stackImageStack: The stack of images to use.
trjTrajectory: The trajectory to project to each time.
radiusint: The stamp radius in pixels. The total stamp width = 2*radius+1.
use_indexlist of bool: A list (vector) of Booleans indicating whether or not to use each time step. An empty (size=0) vector will use all time steps.

Returns:

RawImage: The co-added stamp.

kbmod.search.get_median_stamp(arg0: kbmod.search.ImageStack, arg1: search::Trajectory, arg2: typing.SupportsInt, arg3: list[bool]) → kbmod.search.RawImage#

Create the median co-added stamp centered on the predicted position of an Trajectory at different times. Preserves NO_DATA tag.

Parameters:

stackImageStack: The stack of images to use.
trjTrajectory: The trajectory to project to each time.
radiusint: The stamp radius in pixels. The total stamp width = 2*radius+1.
use_indexlist of bool: A list (vector) of Booleans indicating whether or not to use each time step. An empty (size=0) vector will use all time steps.

Returns:

RawImage: The co-added stamp.

kbmod.search.get_stamps(arg0: kbmod.search.ImageStack, arg1: search::Trajectory, arg2: typing.SupportsInt) → list[kbmod.search.RawImage]#

Create a vector of stamps centered on the predicted position of an Trajectory at different times. Replaces NO_DATA with 0.0 and returns stamps for all time steps.

Parameters:

stackImageStack: The stack of images to use.
trjTrajectory: The trajectory to project to each time.
radiusint: The stamp radius in pixels. The total stamp width = 2*radius+1.

Returns:

list of RawImage: The stamps.

kbmod.search.get_summed_stamp(arg0: kbmod.search.ImageStack, arg1: search::Trajectory, arg2: typing.SupportsInt, arg3: list[bool]) → kbmod.search.RawImage#

Create the summed co-added stamp centered on the predicted position of an Trajectory at different times. Replaces NO_DATA tag with 0.0.

Parameters:

stackImageStack: The stack of images to use.
trjTrajectory: The trajectory to project to each time.
radiusint: The stamp radius in pixels. The total stamp width = 2*radius+1.
use_indexlist of bool: A list (vector) of Booleans indicating whether or not to use each time step. An empty (size=0) vector will use all time steps.

Returns:

RawImage: The co-added stamp.

kbmod.search.get_variance_weighted_stamp(arg0: kbmod.search.ImageStack, arg1: search::Trajectory, arg2: typing.SupportsInt, arg3: list[bool]) → kbmod.search.RawImage#

Create a weighted-mean stamp where the weight for each pixel is 1.0 / variance.

Parameters:

stackImageStack: The stack of images to use.
trjTrajectory: The trajectory to project to each time.
radiusint: The stamp radius in pixels. The total stamp width = 2*radius+1.
use_indexlist of bool: A list (vector) of Booleans indicating whether or not to use each time step. An empty (size=0) vector will use all time steps.

Returns:

RawImage: The co-added stamp.

kbmod.search.pixel_value_valid(arg0: SupportsFloat) → bool#

kbmod.search.print_cuda_stats() → None#: Display the basic GPU information to standard out.

kbmod.search.sigmag_filtered_indices(arg0: list[SupportsFloat], arg1: SupportsFloat, arg2: SupportsFloat, arg3: SupportsFloat, arg4: SupportsFloat) → list[int]#

kbmod.search.stat_gpu_memory_mb() → str#: Create a minimal GPU stats string for debugging.

kbmod.search.validate_gpu(req_memory: SupportsInt = 0) → bool#

Check that a GPU is present, accessible, and has sufficient memory.

Parameters:

req_memoryint: The minimum free memory in bytes. Default: 0

Returns:

bool: Indicates whether the GPU is valid.