LogHeightmaps

struct ExtremaSegments{T}

A class to specify that the spline should be divided into segments between the extrema points of the original spline. min_x_step specifies the minimum difference between control points.

• min_x_step

struct SmoothingSpline3D{T}

A class for the 3D smoothing spline, i.e. a class that holds two splines: X ↦ Y and X ↦ Z. Uses splines from SmoothingSplines.jl.

• splineXY

• splineXZ

• coeffsXY

• coeffsXZ

• cumlengths

SmoothingSpline3D(X, Y, Z; n_segments=ExtremaSegments(5), λ=250.0)

Function that creates a SmoothingSpline3D from given points.

Keywords

• n_segments=ExtremaSegments(5): specifies how to divide the resulting spline into segments. Can be one of 3 possible values: if n_segments::Nothing then original X values will be used to divide the spline into segments. if n_segments::ExtremaSegments then the segments will be chosen according to the extremas of the spline. if n_segments::Integer then range(minimum(X), maximum(X), n_segments+1) will be used as control points.
• λ=250.0: the smoothing parameter. Please refer to SmoothingSplines.jl package for more information.

calculate_heightmap!(heightmap, rescaled_points, α, width, height, real_length; use_cuda=true)

In-place version of the calculate_heightmap function. Calculate heightmap from the points in log-centric coordinate system. rescaled_points must be a 3×n AbstractMatrix, where the rows correspond to l, θ, ρ values respectively, α is a smoothing parameter. It is assumed that l is already rescaled to the [1, height] range, and θ is rescaled to [1, width]. real_length is the difference between minimum and maximum l values before rescaling.

Refer to [1], [2] for more details.

Keywords

• use_cuda=cuda_is_functional(): it is possible to use CUDA to speed up the computation.

calculate_heightmap(rescaled_points, α, width, height, real_length; use_cuda=true)

Calculate heightmap from the points in log-centric coordinate system. rescaled_points must be a 3×n AbstractMatrix, where the rows correspond to l, θ, ρ values respectively, α is a smoothing parameter. It is assumed that l is already rescaled to the [1, height] range, and θ is rescaled to [1, width]. real_length is the difference between minimum and maximum l values before rescaling.

Refer to [1], [2] for more details.

Keywords

• use_cuda=cuda_is_functional(): it is possible to use CUDA to speed up the computation.

filter_point_cloud(data; kws...)

Filter $d × n$ matrix of log point cloud points from noise, where $n$ is the number of points and $d$ is the dimensionality. If $d=3$, assumes that the points are in cartesian coordinates. If $d ≥ 4$, assumes that the first axis corresponds to a number of layer (for a line scanners) and the next 3 are coordinates. It is assumed that the log is oriented along the $z$ axis.

Returns a tuple of (points_filter, circles), where points_filter is a bitarray specifying which points are left after the filtering, and circles is a 4 × m array containing layer number (cross-section index), center x, center y and radius values, and m is the number of layers (cross-sections).

Keywords

• snake_size=180: number of points to use for active contour
• snake_kwparams=(α=0.01, β=0.5, γ=10, σ=20, dist_α=1): keyword parameters for the active contour algorithm defined as a NamedTuple
• min_radius=75: minimum radius of a log cross-section
• max_radius=200: maximum radius of a log cross-section
• max_resiudal=4: maximum residual error
• points_threshold=300: minimum number of points per cross-section
• filtered_threshold=200: minimum number of points to remain after filtering per cross-section.
• max_distance=10: maximum distance from snake.
• max_rad_diff=20: maximum difference in estimated radii.
• snake_coverage=0.8: the required proportion of active contour points that are near the final points.
• snake_iterations=10: iterations for the active contour estimation.
• max_skipped_layers=5: if more layers are skipped, it is assumed that the end of the log has been reached.
• debug_plots=false: specifies whether to plot each layer with filtering information. Requires GLMakie package to be installed.

from_heightmap_coordinates!(points, centerline, width, height, minX=nothing, maxX=nothing)

Convert $3 × n$ matrix of 3D cartesian points to the heightmap coordinates (logcentric coordinates scaled to the size of the heightmap). Applies rescale_points_back and from_logcentric_coordinates.

Refer to [1], [2] for more details.

from_heightmap_coordinates!(points, centerline, width, height, minX=nothing, maxX=nothing)

In-place version of the from_heightmap_coordinates function. Convert $3 × n$ matrix of 3D cartesian points to the heightmap coordinates (logcentric coordinates scaled to the size of the heightmap). Applies rescale_points_back and from_logcentric_coordinates.

Refer to [1], [2] for more details.

from_logcentric_coordinates!(points, centerline)

In-place version of the from_logcentric_coordinates function. Convert 3 × n matrix of logcentric coordinates $l, θ, ρ$ to 3D cartesian points.

Refer to [1], [2] for more details. Note that this conversion differs from the published version and does not approximate centerline as line segments, but works with cubic splines directly.

from_logcentric_coordinates(points, centerline)

Convert 3 × n matrix of logcentric coordinates $l, θ, ρ$ to 3D cartesian points.

Refer to [1], [2] for more details. Note that this conversion differs from the published version and does not approximate centerline as line segments, but works with cubic splines directly.

get_length(spl::SmoothingSpline3D, x; segment_length=false)

Function that returns the length of spline spl at given x. Uses 5-point Gaussian quadratures to approximate the length.

Note: if given x is less than the first control point of spline, the returned value will be negative (because this is used for coordinate transformation).

Keywords

• segment_length=false: whether to compute the length from the first control point or only the length of the segment that contains x

predict_points(spl::SmoothingSpline3D, x)

Evaluate spline spl at points x. Returns a tuple (X, Y, Z) of evaluated coordinates. If multiple values of x were provided, returns Y and Z as vectors of corresponding sizes.

rescale_calculate_heightmap(logcentric_points, α, width, height, min_l=nothing, max_l=nothing, real_length=nothing; use_cuda=cuda_is_functional())

Calculate heightmap from the points in log-centric coordinate system. logcentric_points must be a 3×n AbstractMatrix, where the rows correspond to l, θ, ρ values respectively, α is a smoothing parameter. min_l and max_l are minimum and maximum values of l. If not provided explicitly, estimated from points. real_length is the estimated real length of long. If not provided explicitly, calculated as max_l - min_l.

Refer to [1], [2] for more details.

Keywords

• use_cuda=cuda_is_functional(): it is possible to use CUDA to speed up the computation.

rescale_calculate_heightmap(logcentric_points, α, min_l=nothing, max_l=nothing, real_length=nothing; use_cuda=cuda_is_functional())

In-place version of rescale_calculate_heightmap function. Calculate heightmap from the points in log-centric coordinate system. logcentric_points must be a 3×n AbstractMatrix, where the rows correspond to l, θ, ρ values respectively, α is a smoothing parameter. min_l and max_l are minimum and maximum values of l. If not provided explicitly, estimated from points. real_length is the estimated real length of long. If not provided explicitly, calculated as max_l - min_l.

Refer to [1], [2] for more details.

Keywords

• use_cuda=cuda_is_functional(): it is possible to use CUDA to speed up the computation.

rescale_points!(points, width, height, min_l=nothing, max_l=nothing)

Rescale log-centric points to so that $l ∈ [1, height], θ ∈ [1, width]$. points must be a 3×n AbstractMatrix, where the rows correspond to l, θ, ρ values respectively. min_l and max_l are minimum and maximum values of l. If not provided explicitly, estimated from points.

rescale_points!(points, width, height, min_l=nothing, max_l=nothing)

In-place version of rescale_points function. Rescale log-centric points to so that $l ∈ [1, height], θ ∈ [1, width]$. points must be a 3×n AbstractMatrix, where the rows correspond to l, θ, ρ values respectively. min_l and max_l are minimum and maximum values of l. If not provided explicitly, estimated from points.

rescale_points_back!(points, width, height, min_l, max_l)

In-place version of rescale_points_back function. Rescale log-centric points from $l ∈ [1, height], θ ∈ [1, width]$ to $l ∈ [min_l, max_l], θ ∈ [-π, π]$. points must be a 3×n AbstractMatrix, where the rows correspond to l, θ, ρ values respectively.

rescale_points_back(points, width, height, min_l, max_l)

Rescale log-centric points from $l ∈ [1, height], θ ∈ [1, width]$ to $l ∈ [min_l, max_l], θ ∈ [-π, π]$. points must be a 3×n AbstractMatrix, where the rows correspond to l, θ, ρ values respectively.

segment_branches(I, branch_radius, real_size)

Segment branches from the heightmap image using Difference of Gaussians. branch_radius specifies approximate radius of the branch on the surface in mm. real_size is a tuple containing an estimate of the real size of the heightmap, usually calculated as (real_height, 2π * mean(heightmap)).

Refer to [1], [2] for more details.

to_heightmap_coordinates(points, centerline, width, height, minX=nothing, maxX=nothing)

Convert 3 × n matrix of 3D cartesian points to the heightmap coordinates (logcentric coordinates scaled to the size of the heightmap). Applies to_logcentric_coordinates and rescale_points.

Refer to [1], [2] for more details.

to_heightmap_coordinates!(points, centerline, width, height, minX=nothing, maxX=nothing)

In-place version of the to_heightmap_coordinates function. Convert 3 × n matrix of 3D cartesian points to the heightmap coordinates (logcentric coordinates scaled to the size of the heightmap). Applies to_logcentric_coordinates and rescale_points.

Refer to [1], [2] for more details.

to_logcentric_coordinates!(points, centerline)

In-place version of the to_logcentric_coordinates function. Convert 3 × n matrix of 3D cartesian points to the logcentric coordinates $l, θ, ρ$.

Refer to [1], [2] for more details. Note that this conversion differs from the published version and does not approximate centerline as line segments, but works with cubic splines directly.

to_logcentric_coordinates(points, centerline)

Convert 3 × n matrix of 3D cartesian points to the logcentric coordinates $l, θ, ρ$.

Refer to [1], [2] for more details. Note that this conversion differs from the published version and does not approximate centerline as line segments, but works with cubic splines directly.