runlength_featuresRunlengthFeaturesRunlengthFeaturesrunlength_featuresrunlength_features

HALCON ScriptCpp++.NETPythonC

Short description

runlength_featuresRunlengthFeaturesRunlengthFeaturesrunlength_featuresrunlength_features — Characteristic values for runlength coding of regions.

Signature

runlength_features( region Regions, out integer NumRuns, out real KFactor, out real LFactor, out real MeanLength, out integer Bytes )void RunlengthFeatures( const HObject& Regions, HTuple* NumRuns, HTuple* KFactor, HTuple* LFactor, HTuple* MeanLength, HTuple* Bytes )static void HOperatorSet.RunlengthFeatures( HObject regions, out HTuple numRuns, out HTuple KFactor, out HTuple LFactor, out HTuple meanLength, out HTuple bytes )def runlength_features( regions: HObject ) -> Tuple[Sequence[int], Sequence[float], Sequence[float], Sequence[float], Sequence[int]]

def runlength_features_s( regions: HObject ) -> Tuple[int, float, float, float, int]Herror runlength_features( const Hobject Regions, Hlong* NumRuns, double* KFactor, double* LFactor, double* MeanLength, Hlong* Bytes )

Herror T_runlength_features( const Hobject Regions, Htuple* NumRuns, Htuple* KFactor, Htuple* LFactor, Htuple* MeanLength, Htuple* Bytes )

HTuple HRegion::RunlengthFeatures( HTuple* KFactor, HTuple* LFactor, HTuple* MeanLength, HTuple* Bytes ) const

Hlong HRegion::RunlengthFeatures( double* KFactor, double* LFactor, double* MeanLength, Hlong* Bytes ) const

HTuple HRegion.RunlengthFeatures( out HTuple KFactor, out HTuple LFactor, out HTuple meanLength, out HTuple bytes )

int HRegion.RunlengthFeatures( out double KFactor, out double LFactor, out double meanLength, out int bytes )

Description

The operator runlength_featuresRunlengthFeatures calculates for every input region from Regionsregionsregions the number of runs necessary for storing this region with the aid of runlength coding. Furthermore the so-called “K-factor” is determined, which indicates by how much the number of runs differs from the ideal of the square in which this value is 1.0.

The K-factor (KFactorKFactorkfactor) is calculated according to the formula:

\[\begin{eqnarray*} \textrm{KFactor} = \frac{\textrm{NumRuns}}{\sqrt{Area}} \end{eqnarray*}\]

wherein \(Area\) indicates the area of the region. It should be noted that the K-factor can be smaller than 1.0 (in case of long horizontal regions).

The L-factor (LFactorLFactorlfactor) indicates the mean number of runs for each line index occurring in the region.

MeanLengthmeanLengthmean_length indicates the mean length of the runs. The parameter Bytesbytesbytes indicates how many bytes are necessary for coding the region with runlengths.

Attention

All features calculated by the operator runlength_featuresRunlengthFeatures are not rotation invariant because the runlength coding depends on the direction. The operator runlength_featuresRunlengthFeatures does not serve for calculating shape features but for controlling and analyzing the efficiency of the runlength coding.

Execution information

Execution information

• Multithreading type: reentrant (runs in parallel with non-exclusive operators).

• Multithreading scope: global (may be called from any thread).

• Automatically parallelized on tuple level.

Parameters

Regionsregionsregions (input_object) region(-array) → objectHObjectHRegionHObjectHobject

Regions to be examined.

NumRunsnumRunsnum_runs (output_control) integer(-array) → (integer)HTuple (Hlong)HTuple (int / long)Sequence[int]Htuple (Hlong)

Number of runs.

Assertion: 0 <= NumRuns

KFactorKFactorkfactor (output_control) real(-array) → (real)HTuple (double)HTuple (double)Sequence[float]Htuple (double)

Storing factor in relation to a square.

Assertion: 0 <= KFactor

LFactorLFactorlfactor (output_control) real(-array) → (real)HTuple (double)HTuple (double)Sequence[float]Htuple (double)

Mean number of runs per line.

Assertion: 0 <= LFactor

MeanLengthmeanLengthmean_length (output_control) real(-array) → (real)HTuple (double)HTuple (double)Sequence[float]Htuple (double)

Mean length of runs.

Assertion: 0 <= MeanLength

Bytesbytesbytes (output_control) integer(-array) → (integer)HTuple (Hlong)HTuple (int / long)Sequence[int]Htuple (Hlong)

Number of bytes necessary for coding the region.

Assertion: 0 <= Bytes

Complexity

The mean runtime complexity is \(O(1)\).

Result

The operator runlength_featuresRunlengthFeatures returns the value 2 (H_MSG_TRUE) if the input is not empty. If necessary an exception is raised.

Combinations with other operators

Combinations

Possible predecessors

thresholdThreshold, regiongrowingRegiongrowing, connectionConnection

See also

runlength_distributionRunlengthDistribution

Module

Foundation