Functions
NDArray	r (NDArray img, NDArray out, float g, float sigma, float shadows, float highlights, float clarity)

Sequence[NDArray]	makeGaussianPyramid (NDArray img, list[int] padY, list[int] padX, List[NDArray]\|None out)

Sequence[NDArray]	makeLapPyramid (NDArray img, list[int] padY, list[int] padX, List[NDArray]\|None gaussOut, List[NDArray]\|None lapOut, List[NDArray]\|None upscratch=None)

	_calculateOutput (List[NDArray] out, List[NDArray] pyramid, NDArray gamma, List[NDArray] pyramidVectorsBottom, List[NDArray] pyramidVectorsTop)

list[int]	levelPadder (int numb, int levels)

NDArray	localContrast (NDArray image, float sigma, float highlights=-0.9, float shadows=0.4, float clarity=0.15, int\|None maxLevel=None, int numGamma=20, int skipLevels=0)

Function Documentation

◆ _calculateOutput()

lsst.pipe.tasks.prettyPictureMaker._localContrast._calculateOutput	(	List[NDArray]	out,
		List[NDArray]	pyramid,
		NDArray	gamma,
		List[NDArray]	pyramidVectorsBottom,
		List[NDArray]	pyramidVectorsTop )

protected

Computes the output by interpolating between basis vectors at each pixel in
a Gaussian pyramid.

The function iterates over each pixel in the Gaussian pyramids
and interpolates between the corresponding basis vectors  from
`pyramidVectorsBottom` and `pyramidVectorsTop`. If a pixel value is outside
the range defined by gamma, it skips interpolation.

Parameters
----------
out : `~numba.typed.typedlist.List` of `numpy.ndarray`
    A list of numpy arrays representing the output image pyramids.
pyramid : `~numba.typed.typedlist.List` of `numpy.ndarray`
    A list of numpy arrays representing the Gaussian pyramids.
gamma : `numpy.ndarray`
    A numpy array containing the range for pixel values to be considered in
    the interpolation.
pyramidVectorsBottom : `~numba.typed.typedlist.List` of `numpy.ndarray`
    A list of numpy arrays representing the basis vectors at the bottom
    level of each pyramid layer.
pyramidVectorsTop : `~numba.typed.typedlist.List` of `numpy.ndarray`
    A list of numpy arrays representing the basis vectors at the top level
    of each pyramid layer.

Definition at line 238 of file _localContrast.py.

◆ levelPadder()

list[int] lsst.pipe.tasks.prettyPictureMaker._localContrast.levelPadder	(	int	numb,
		int	levels )

Determine if each level of transform will need to be padded by one to
ensure the level is divisible by two.

Parameters
----------
numb : `int`
    The size of the input dimension
levels : `int`
    The number of times the dimensions will be reduced by a factor of two

Returns
-------
pads : `list` of `int`
    A list where the entries are either zero or one depending on if the
    size will need pad to be a power of two.

Definition at line 292 of file _localContrast.py.

◆ localContrast()

NDArray lsst.pipe.tasks.prettyPictureMaker._localContrast.localContrast	(	NDArray	image,
		float	sigma,
		float	highlights = -0.9,
		float	shadows = 0.4,
		float	clarity = 0.15,
		int \| None	maxLevel = None,
		int	numGamma = 20,
		int	skipLevels = 0 )

Enhance the local contrast of an input image.

Parameters
----------
image : `numpy.ndarray`
    Two dimensional numpy array representing the image to have contrast
    increased. Data must be in the range 0 to 1.
sigma : `float`
    The scale over which edges are considered real and not noise.
highlights : `float`
    A parameter that controls how highlights are enhanced or reduced,
    contrary to intuition, negative values increase highlights.
shadows : `float`
    A parameter that controls how shadows are deepened.
clarity : `float`
    A parameter that relates to the contrast between highlights and
    shadow.
maxLevel : `int` or `None`
    The maximum number of image pyramid levels to enhance the contrast over.
    Each level has a spatial scale of roughly 2^(level) pixels.
numGamma : `int`
    This is an optimization parameter. This algorithm divides up contrast
    space into a certain number of bins over which the expensive computation
    is done. Contrast values in the image which fall between two of these
    values are interpolated to get the outcome. The higher the numGamma,
    the smoother the image is post contrast enhancement, though above
    some number there is no discernible difference.
skipLevels : `int`
    When calculating the local contrast skip the specified number of levels
    starting at the lowest level.

Returns
-------
image : `numpy.ndarray`
    Two dimensional numpy array of the input image with increased local
    contrast.

Raises
------
ValueError
    Raised if the max level to enhance to is greater than the image
    supports.

Notes
-----
This function, and its supporting functions, spiritually implement the
algorithm outlined at
https://people.csail.mit.edu/sparis/publi/2011/siggraph/
titled "Local Laplacian Filters: Edge-aware Image Processing with Laplacian
Pyramid". This is not a 1:1 implementation, it's optimized for the
python language and runtime performance. Most notably it transforms only
certain levels and linearly interpolates to find other values. This
implementation is inspired by the one done in the darktable image editor:
https://www.darktable.org/2017/11/local-laplacian-pyramids/. None of the
code is in common, nor is the implementation 1:1, but reading the original
paper and the darktable implementation gives more info about this function.
Specifically some variable names follow the paper/other implementation,
and may be confusing when viewed without that context.

Definition at line 326 of file _localContrast.py.

◆ makeGaussianPyramid()

Sequence[NDArray] lsst.pipe.tasks.prettyPictureMaker._localContrast.makeGaussianPyramid	(	NDArray	img,
		list[int]	padY,
		list[int]	padX,
		List[NDArray] \| None	out )

Create a Gaussian Pyramid from an input image.

Parameters
----------
img : `numpy.ndarray`
    The input image, which will be processed to create the pyramid.
padY : `list` of `int`
    List containing padding sizes along the Y-axis for each level of the pyramid.
padX : `list` of `int`
    List containing padding sizes along the X-axis for each level of the pyramid.
out : `~numba.typed.typedlist.List` of `NDArray` or `None`
    Optional list to store the output images of the pyramid levels.
    If None, a new list is created.

Returns
-------
pyramid : `~collections.abc.sequence` of `numpy.ndarray`
    A sequence of images representing the Gaussian Pyramid.

Notes
-----
- The function creates a padded version of the input image and then
  reduces its size using `cv2.pyrDown` to generate each level of the
  pyramid.
- If 'out' is provided, it will be used to store the pyramid levels;
  otherwise, a new list is dynamically created.
- Padding is applied only if specified by non-zero values in `padY` and
  `padX`.

Definition at line 104 of file _localContrast.py.

◆ makeLapPyramid()

Sequence[NDArray] lsst.pipe.tasks.prettyPictureMaker._localContrast.makeLapPyramid	(	NDArray	img,
		list[int]	padY,
		list[int]	padX,
		List[NDArray] \| None	gaussOut,
		List[NDArray] \| None	lapOut,
		List[NDArray] \| None	upscratch = None )

Create a Laplacian pyramid from the input image.

This function constructs a Laplacian pyramid from the input image. It first
generates a Gaussian pyramid and then, for each level (except the last),
subtracts the upsampled version of the next lower level from the current
level to obtain the Laplacian levels. If `lapOut` is None, it creates a
new list to store the Laplacian pyramid; otherwise, it uses the provided
`lapOut`.

Parameters
----------
img : `numpy.ndarray`
    The input image as a numpy array.
padY : `list` of `int`
    List of padding sizes for rows (vertical padding).
padX : `list` of `int`
    List of padding sizes for columns (horizontal padding).
gaussOut : `~numba.typed.typedlist.List` of `numpy.ndarray` or None
    Preallocated storage for the output of the Gaussian pyramid function.
    If `None` new storage is allocated.
lapOut : `~numba.typed.typedlist.List` of `numpy.ndarray` or None
    Preallocated for the output Laplacian pyramid. If None, a new
    `List` is created.
upscratch : `~numba.typed.typedlist.List` of `numpy.ndarray`, optional
    List to store intermediate results of pyramids (default is None).

Returns
-------
results : `~collections.abc.sequence` of `numpy.ndarray`
    The Laplacian pyramid as a sequence of numpy arrays.

Definition at line 174 of file _localContrast.py.

◆ r()

NDArray lsst.pipe.tasks.prettyPictureMaker._localContrast.r	(	NDArray	img,
		NDArray	out,
		float	g,
		float	sigma,
		float	shadows,
		float	highlights,
		float	clarity )

Apply a post-processing effect to an image using the specified parameters.

Parameters
----------
img : `numpy.ndarray`
    The input image array of shape (n_images, height, width).
out : `numpy.ndarray`
    The output image array where the result will be stored. Should have the same shape as `img`.
g : `float`
    A parameter for gamma correction.
sigma : `float`
    Parameter that defines the scale at which a change should be considered an edge.
shadows : `float`
    Shadow adjustment factor.
highlights : `float`
    Highlight adjustment factor. Negative values INCREASE highlights.
clarity : `float`
    Clarity adjustment factor.

Returns
-------
result : `numpy.ndarray`
    The processed image array with the same shape as `out`.

Definition at line 36 of file _localContrast.py.