Back to FabImage Library website

You are here: Start » Function Reference » Profile » Profile Metrics » ProfileAutocorrelation

ProfileAutocorrelation


Header: FIL.h
Namespace: fil
Module: FoundationPro

Computes the correlation between neighboring sub-profiles of different sizes and infers the most probable period length.

Syntax

C++
C#
 
void fil::ProfileAutocorrelation
(
	const fil::Profile& inProfile,
	int inStart,
	int inMinPeriod,
	int inMaxPeriod,
	int inMinVerifiedLength,
	bool inFlexibleVerification,
	int inMinRepeatCount,
	float inHarmonicHysteresis,
	fil::PeriodPrecisionMethod::Type inPrecisionMethod,
	ftl::Array< float >& outAutocorrelationValues,
	float& outPeriod,
	float& outPeriodScore
)

Parameters

Name Type Range Default Description
Input value inProfile const Profile& Input profile
Input value inStart int 0 - Beginning index of the sub-profile of interest
Input value inMinPeriod int 2 - 2 Minimum period length
Input value inMaxPeriod int 2 - 2 Maximum period length
Input value inMinVerifiedLength int 1 - 1 Minimum number of profile points that verify single period (increases the actual RepeatCount for small periods)
Input value inFlexibleVerification bool Compensates errors resulting from whole-pixel precision
Input value inMinRepeatCount int 1 - 1 The number of repeats for sufficiently big periods
Input value inHarmonicHysteresis float 0.0 - 1.0 0.05f Defines how much better must be the period T than T/2, T/3 etc. to be accepted
Input value inPrecisionMethod PeriodPrecisionMethod::Type Defines if and how sub-point precision is achieved
Output value outAutocorrelationValues Array< float >& Autocorrelation values for consecutive period values
Output value outPeriod float& Estimated period length
Output value outPeriodScore float& Correlation value for the estimated period length

Description

This filter is usually used to find a period within a profile. It tests all possible periods from the range inMinPeriod and inMaxPeriod. For each candidate period it creates several sub-profiles of that size and computes the normalized correlation between the first one and the others. As the final score, the minimum of the correlations is taken. The number of sub-profiles that is used is determined with the inMinRepeatCount and inMinVerifiedLength inputs. The latter is used to increase the number of sub-profiles that are used for small period candidates, which often cause false high-scoring periods when used without this parameter. Furthermore, as for any good period of the length T, the periods of the length T * 2, T * 3 etc. also score high, the inHarmonicHysteresis input can be used to define the minimum difference between the score of the tested period (T) and its integer partitions (T/2, T/3, ...).

Examples

On this profile the ProfileAutocorrelation filter finds a period of length 302 and score 0.998.

Hardware Acceleration

This operation supports automatic parallelization for multicore and multiprocessor systems.

This operation is optimized for AVX2 technology.

Errors

List of possible exceptions:

Error type Description
DomainError inMinPeriod is larger than inMaxPeriod in ProfileAutocorrelation.
DomainError inStart + inMinVerifiedLength is larger than the profile size in ProfileAutocorrelation.
DomainError The range of applicable profile periods is empty in ProfileAutocorrelation.