Back to FabImage Library website

You are here: Start » Function Reference » All Functions » Image Point Transforms » FisFilter_LogarithmImage

FisFilter_LogarithmImage


This is Filter Equivalent. This function may be present in generated code, but should not be used in hand-written code. CreateLogarithmLut and ApplyPixelLut should be used instead.

Header: FIL.h
Namespace: fis
Module: FoundationLite

Computes a natural logarithm of each pixel.

Applications: Transforms an image in such a way that a quotient on the input image becomes a difference on the output image. This can be useful for dealing with variable illumination.

Syntax

void fis::FisFilter_LogarithmImage
(
	FisFilters_ImagePointTransformsState& ioState,
	const fil::Image& inImage,
	ftl::Optional<const fil::Region&> inRoi,
	ftl::Optional<const float&> inScale,
	float inOffset,
	bool inNormalizeZero,
	fil::Image& outImage,
	fil::Profile& diagLutProfile
)

Parameters

Name Type Range Default Description
Input will be modified ioState FisFilters_ImagePointTransformsState& Object used to maintain state of the function.
Input value inImage const Image& Input image
Input value inRoi Optional<const Region&> NIL Region of interest
Input value inScale Optional<const float&> NIL Scaling factor (default: 255)
Input value inOffset float 1.0 - 1.0f Offset factor
Input value inNormalizeZero bool Specifies whether the output range should be rescaled to start from 0
Output value outImage Image& Output image
Diagnostic input diagLutProfile Profile& Profile depicting the resulting look-up table of the logarithm transform

Requirements

For input inImage only pixel formats are supported: int8, uint8, int16, uint16, int32.

Read more about pixel formats in Image documentation.

In-place Processing

This function supports in-place data processing - you can pass the same reference to inImage and outImage

Read more about In-place Computation.

Description

The operation applies logarithmic operator to each pixel of an image. Logarithmic operator is defined as follows:

\[inScale \cdot \frac{log(inOffset + |P(x,y)|)}{log(inOffset + M)}\]
where:

  • M is the maximum of the inImage type (i.e. 255 for UInt8, 127 for Int8).
  • inScale is the expected maximum value of the transformation. If set to Auto it will result in value 127 for Int8 image and 255 for other image types.
  • inOffset value corresponds to the camera's black level. Its default value is equal 1 and causes the strongest possible transform.

When inNormalizeZero is set to True, the result is not only scaled, but also normalized so that pixel value 0 is still transformed into value 0. This assures that the entire output value range is utilized.

Examples

The LogarithmImage performed on the sample image with parameters inScale = 250, inOffset = 50. The middle image inNormalizeZero = False and the left image has inNormalizeZero = True.

Hardware Acceleration

This operation supports automatic parallelization for multicore and multiprocessor systems.

Errors

List of possible exceptions:

Error type Description
DomainError Region exceeds an input image in LogarithmImage.
DomainError Not supported inImage pixel format in FisFilter_LogarithmImage. Supported formats: Int8, UInt8, Int16, UInt16, Int32.