From e413c6e3872baea5a1a9a8fcbb7cfc79963eca16 Mon Sep 17 00:00:00 2001 From: Edwin Jakobs Date: Fri, 24 Jan 2025 16:24:12 +0100 Subject: [PATCH] [orx-jumpflood] Add generated and verified documentation --- .../src/commonMain/kotlin/DirectionalField.kt | 33 +++++++++++++++++++ .../src/commonMain/kotlin/DistanceField.kt | 19 +++++++++++ 2 files changed, 52 insertions(+) diff --git a/orx-jumpflood/src/commonMain/kotlin/DirectionalField.kt b/orx-jumpflood/src/commonMain/kotlin/DirectionalField.kt index 4df49402..dd1ec1bf 100644 --- a/orx-jumpflood/src/commonMain/kotlin/DirectionalField.kt +++ b/orx-jumpflood/src/commonMain/kotlin/DirectionalField.kt @@ -14,6 +14,39 @@ import kotlin.math.log2 import kotlin.math.max import kotlin.math.pow + +/** + * DirectionalField is a filter that generates a directional field representation + * of an input image, utilizing operations such as thresholding, contour detection, + * jump flooding, and direction decoding. The generated output encodes directional + * and distance information from the contours of the input. + * + * The filter supports a variety of configurable properties such as thresholds, + * scaling, and different modes for direction and magnitude representation. + * + * This class extends Filter1to1, processing one input `ColorBuffer` and producing + * one output `ColorBuffer`. + * + * Parameters: + * - `threshold`: The threshold value used during the binary segmentation of the input image. + * - `distanceScale`: The scale factor applied to the distance values encoded in the output. + * - `normalizedDistance`: Whether to normalize the distance values in the output. + * - `unitDirection`: Whether to represent gradient directions as unit vectors. + * - `signedMagnitude`: Whether to encode magnitude with signed values. + * - `flipV`: Whether to flip the vertical component of the direction vectors in the output. + * + * Lifecycle: + * - Resources such as intermediate `ColorBuffer` instances are created dynamically + * based on the dimensions of the input image. These resources are cleaned up + * in the `destroy` method to prevent memory leaks. + * + * Responsibilities: + * - Threshold the input to create a binary image. + * - Detect contours from the thresholded image. + * - Generate a jump flood field to calculate distance and direction information. + * - Decode directional data into the final output. + * + */ @Description("Directional field") class DirectionalField : Filter1to1() { @DoubleParameter("threshold", 0.0, 1.0) diff --git a/orx-jumpflood/src/commonMain/kotlin/DistanceField.kt b/orx-jumpflood/src/commonMain/kotlin/DistanceField.kt index ce251acb..e9079cac 100644 --- a/orx-jumpflood/src/commonMain/kotlin/DistanceField.kt +++ b/orx-jumpflood/src/commonMain/kotlin/DistanceField.kt @@ -14,6 +14,25 @@ import kotlin.math.log2 import kotlin.math.max import kotlin.math.pow +/** + * The `DistanceField` class provides an implementation for computing a distance field representation of an image. + * The distance field calculation is achieved via mechanisms like thresholding, contour tracing, and jump flooding. + * This class can operate on a single source image and produce a single target image. + * + * The distance field process involves: + * - Applying a threshold filter to the source image to create a binary image representation. + * - Computing the contours of the binary representation. + * - Using a jump flooding algorithm to compute distances from each pixel to the nearest contour point. + * - Optionally utilizing signed distances by distinguishing between pixels inside and outside the contour. + * + * The class uses several configurable parameters and intermediate processing steps: + * - `threshold`: Controls the binary threshold level used in the threshold filter. + * - `distanceScale`: Scales the computed distance field values. + * - `signedDistance`: Indicates whether the distance field should contain signed or unsigned distances. + * + * Internal optimizations include resizing the input to power-of-two dimensions for efficient processing, and reusing + * intermediate buffers to reduce memory allocation overhead. + */ @Description("Distance field") class DistanceField : Filter1to1() { @DoubleParameter("threshold", 0.0, 1.0)