API Reference

This page documents all the exported functions and types in DistanceTransforms.jl.

## `boolean_indicator`

```julia
boolean_indicator(f::AbstractArray)
boolean_indicator(f::AbstractGPUArray)
boolean_indicator(f::BitArray)

Create a float representation of a boolean indicator array where 0 represents the background and 1 represents the foreground. This function converts a logical array into a floating-point array where foreground values (logical 1) are marked as 0.0f0 (float representation of 0), and background values (logical 0) are marked with a large float number 1.0f10. This representation is useful in distance transform operations to differentiate between the foreground and the background.

Arguments

f: An array of boolean values or an AbstractGPUArray of boolean values, where true indicates the foreground and false indicates the background.

Returns

A floating-point array of the same dimensions as f, with foreground values set to 0.0f0 and background values set to 1.0f10.

Performance

If f is a BitArray, the conversion uses LoopVectorization.jl for a potential speedup. The warning check arguments are disabled for performance reasons.
If f is an AbstractGPUArray, the computation is offloaded to the GPU using a custom kernel, boolean_indicator_kernel, which is expected to yield a significant speedup on compatible hardware.

Examples

f = BitArray([true, false, true, false])
f_float = boolean_indicator(f)
# f_float will be Float32[0.0f0, 1.0f10, 0.0f0, 1.0f10]

f_gpu = CUDA.zeros(Bool, 10) # assuming CUDA.jl is used for GPU arrays
f_gpu[5] = true
f_float_gpu = boolean_indicator(f_gpu)
# f_float_gpu will be a GPU array with the fifth element as 0.0f0 and others as 1.0f10

Notes

The choice of 1.0f10 as the large number is arbitrary and can be adjusted if needed for specific applications.
When f is an AbstractGPUArray, the boolean_indicator_kernel kernel function is used to perform the operation in parallel on the GPU.
The KernelAbstractions.synchronize(backend) call ensures that all GPU operations are completed before returning the result.

`transform`

transform(f::AbstractVector)
transform(img::AbstractMatrix; threaded=true)
transform(vol::AbstractArray{<:Real,3}; threaded=true)
transform(img::AbstractGPUMatrix)

Non-in-place squared Euclidean distance transforms that return a new array with the result. They allocate necessary intermediate arrays internally.

The first function operates on vectors.
The second function operates on matrices with optional threading.
The third function operates on 3D arrays with optional threading.
The fourth function is specialized for GPU matrices.

The threaded parameter can be used to enable or disable parallel computation on the CPU.

Arguments

f/img/vol: Input vector, matrix, or 3D array to be transformed.

Examples

f = rand([0f0, 1f0], 10)
f_bool = boolean_indicator(f)
f_tfm = transform(f_bool)

`transform!`

transform!(f::AbstractVector, output, v, z)
transform!(img::AbstractMatrix, output, v, z; threaded=true)
transform!(vol::AbstractArray{<:Real,3}, output, v, z, temp; threaded=true)
transform!(img::AbstractGPUMatrix, output, v, z)

In-place squared Euclidean distance transforms. These functions apply the transform to the input data and store the result in the output argument.

The first function operates on vectors.
The second function operates on matrices with optional threading.
The third function operates on 3D arrays with optional threading.
The fourth function is specialized for GPU matrices.

The intermediate arrays v and z (and temp for 3D arrays) are used for computation. The threaded parameter enables parallel computation on the CPU.

Arguments

f: Input vector, matrix, or 3D array.
output: Preallocated array to store the result.
v: Preallocated array for indices, matching the dimensions of f.
z: Preallocated array for intermediate values, one element larger than f.
temp: Preallocated array for intermediate values when transforming 3D arrays, matching the dimensions of output.

Examples

f = rand([0f0, 1f0], 10)
f_bool = boolean_indicator(f)
output = similar(f)
v = ones(Int32, size(f))
z = ones(eltype(f), size(f) .+ 1)
transform!(f_bool, output, v, z)

:::
:::






:::{#quarto-navigation-envelope .hidden}
[Julia]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1zaWRlYmFyLXRpdGxl"}
[Distance Transforms]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXItdGl0bGU="}
[User Guide]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1wcmV2"}
[Overview]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1zaWRlYmFyOi9qdWxpYS9pbmRleC5odG1sT3ZlcnZpZXc="}
[User Guide]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1zaWRlYmFyOi9qdWxpYS9ndWlkZS5odG1sVXNlci1HdWlkZQ=="}
[API Reference]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1zaWRlYmFyOi9qdWxpYS9hcGkuaHRtbEFQSS1SZWZlcmVuY2U="}
[Home]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6SG9tZQ=="}
[/index.html]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6L2luZGV4Lmh0bWw="}
[Julia]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6SnVsaWE="}
[Overview]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6T3ZlcnZpZXc="}
[/julia/index.html]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6L2p1bGlhL2luZGV4Lmh0bWw="}
[User Guide]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6VXNlciBHdWlkZQ=="}
[/julia/guide.html]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6L2p1bGlhL2d1aWRlLmh0bWw="}
[API Reference]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6QVBJIFJlZmVyZW5jZQ=="}
[/julia/api.html]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6L2p1bGlhL2FwaS5odG1s"}
[Python]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6UHl0aG9u"}
[/python/index.html]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6L3B5dGhvbi9pbmRleC5odG1s"}
[/python/guide.html]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6L3B5dGhvbi9ndWlkZS5odG1s"}
[/python/api.html]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6L3B5dGhvbi9hcGkuaHRtbA=="}
[About]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6QWJvdXQ="}
[/about.html]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6L2Fib3V0Lmh0bWw="}
[https://github.com/MolloiLab/DistanceTransforms.jl]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWludC1uYXZiYXI6aHR0cHM6Ly9naXRodWIuY29tL01vbGxvaUxhYi9EaXN0YW5jZVRyYW5zZm9ybXMuamw="}
[API Reference]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLWJyZWFkY3J1bWJzLUFQSS1SZWZlcmVuY2U="}

:::{.hidden .quarto-markdown-envelope-contents render-id="Zm9vdGVyLWxlZnQ="}
Copyright 2024, Dale Black
:::

:::



:::{#quarto-meta-markdown .hidden}
[API Reference – Distance Transforms]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLW1ldGF0aXRsZQ=="}
[API Reference – Distance Transforms]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLXR3aXR0ZXJjYXJkdGl0bGU="}
[API Reference – Distance Transforms]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLW9nY2FyZHRpdGxl"}
[Distance Transforms]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLW1ldGFzaXRlbmFtZQ=="}
[Efficient distance transform operations for CPU and GPU in Julia and Python]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLXR3aXR0ZXJjYXJkZGVzYw=="}
[Efficient distance transform operations for CPU and GPU in Julia and Python]{.hidden .quarto-markdown-envelope-contents render-id="cXVhcnRvLW9nY2FyZGRkZXNj"}
:::




<!-- -->

::: {.quarto-embedded-source-code}
```````````````````{.markdown shortcodes="false"}
---
title: "API Reference"
sidebar: julia
format:
  html:
    toc: true
    cold-fold: true
execute:
  engine: julia
---

This page documents all the exported functions and types in DistanceTransforms.jl.

quarto-executable-code-5450563D

```julia
#| echo: false


using DistanceTransforms
using Markdown

"""
    generate_markdown_docs()
    
Generate Markdown documentation for all exported functions in DistanceTransforms.jl,
returning a single string with properly formatted markdown.
"""
function generate_markdown_docs()
    # Get all exported names from DistanceTransforms
    all_names = names(DistanceTransforms)
    exported_functions = filter(x -> x != :DistanceTransforms, all_names)
    
    # Create a string buffer to collect all output
    result = IOBuffer()
    
    # Generate documentation for each function
    for name in exported_functions
        
        # Get the documentation and convert it to string
        doc = getproperty(DistanceTransforms, name)
        doc_string = string(Docs.doc(doc))
        
        # Write the documentation
        write(result, doc_string)
        write(result, "\n\n---\n\n")
    end
    
    # Return the collected documentation as a string
    return String(take!(result))
end

# Call the function to generate the documentation
docs = generate_markdown_docs()

println(docs)

```````````````````