Package 'morph'

Title: 3D Segmentation of Voxels into Morphologic Classes
Description: Automatically segments a 3D array of voxels into mutually exclusive morphological elements. This package extends existing work for segmenting 2D binary raster data. A paper documenting this approach has been accepted for publication in the journal Landscape Ecology. Detailed references will be updated here once those are known.
Authors: Tarmo K. Remmel [aut, cre]
Maintainer: Tarmo K. Remmel <[email protected]>
License: GPL-3
Version: 1.1.0
Built: 2024-12-21 06:39:58 UTC
Source: CRAN

Help Index

3D Segmentation of Voxels into Morphologic Classes

Description

Automatically segments a 3D array of voxels into mutually exclusive morphological elements. This package extends existing work for segmenting 2D binary raster data. A paper documenting this approach has been accepted for publication in the journal Landscape Ecology. Detailed references will be updated here once those are known.

Details

The DESCRIPTION file:

Package: morph
Type: Package
Title: 3D Segmentation of Voxels into Morphologic Classes
Version: 1.1.0
Date: 2023-02-14
Authors@R: c( person("Tarmo K.", "Remmel", email = "[email protected]", role = c("aut", "cre"), comment = c(ORCID = "0000-0001-6251-876X")))
Maintainer: Tarmo K. Remmel <[email protected]>
Description: Automatically segments a 3D array of voxels into mutually exclusive morphological elements. This package extends existing work for segmenting 2D binary raster data. A paper documenting this approach has been accepted for publication in the journal Landscape Ecology. Detailed references will be updated here once those are known.
License: GPL-3
LazyData: true
LazyDataCompression: xz
Depends: R (>= 4.1.0), rgl, reshape2, igraph, stringr
NeedsCompilation: no
Repository: CRAN
Packaged: 2023-02-14 15:25:34 UTC; tarmo
Author: Tarmo K. Remmel [aut, cre] (<https://orcid.org/0000-0001-6251-876X>)
Date/Publication: 2023-02-14 15:40:02 UTC
Config/pak/sysreqs: libfreetype6-dev libglpk-dev libglu1-mesa-dev make libicu-dev libpng-dev libxml2-dev libgl1-mesa-dev zlib1g-dev

Index of help topics: 

LEdemo                  Landscape Ecology Demo Data (3D Voxels)
arraytrim               Trim excess white-space (0 planes) from a 3D
                        binary array.
morph-package           3D Segmentation of Voxels into Morphologic
                        Classes
morph3d                 Performs a morphological segmentation of a
                        binary 3D array
morph3dlinks            An internal function that computes the spatial
                        neighbours for voxels. It is an internal
                        function called by morph3d() and not intended
                        to be called on its own.
morph3dplot             A plot function that converts a 3D array of
                        voxels into an interactive rgl plot.
morph3dprep             Prepare 3D voxel data for interactive 3D
                        plotting.

This package handles the segmentation of binary voxel data, provided as a numeric 3D array, into its constituent morphological classes. Each voxel is assigned to one of nine mutually exclusive morpholocal classes: outside, mass, skin, crumb, circuit, antenna, bond, void-volume, or void.

Author(s)

Tarmo K. Remmel [aut, cre] (<https://orcid.org/0000-0001-6251-876X>) Maintainer: Tarmo K. Remmel <[email protected]>

References

Remmel, T.K. 2022. Extending morphological pattern analysis to 3D voxels. Landscape Ecology 37(2):373-380.

See Also

See Also melt

Examples

# Need to provide some simple examples here.

Trim excess white-space (0 planes) from a 3D binary array.

Description

A helper function for reducing the size of 3D arrays if necessary. This reduction can improve memory utilization and speed processing, since voxels outside the feature of interest are eliminated.

Usage

arraytrim(VOLOBJ = NULL)

Arguments

VOLOBJ

This is a 3D binary (0,1) numeric array, which represent voxels. If there are outter margins that are all zeros, they will be trimmed off to reduce the size of the array.

Details

The function scans inward, starting at the outer margins, for planes that are all zeros. If they are, those planes will be trimmed at the end. Only planes of zeros that connect contiguously to the outer margins will be trimmed.

Value

The output is an array with the excess outter zero planes removed.

Note

It can happen that trimming reduces the resulting dimensions to be <3, and thus, prior to running morph3d(), ensure that your data still fits the requirements.

Author(s)

Tarmo K. Remmel

References

Remmel, T.K. 2022. Extending morphological pattern analysis to 3D voxels. Landscape Ecology 37(2):373-380.

See Also

See Also morph3d, morph3dprep

Examples

LEdemoSmall <- arraytrim(LEdemo)

Landscape Ecology Demo Data (3D Voxels)

Description

This is a 3D numeric array with dimensions [10,10,10], representing 1000 voxels for demonstration purposes. The data was manually produced to ensure that all morphological classes are present, to allow demonstration and illustration within the Landscape Ecology paper in which the morph3d() functionality was introduced.

Usage

data("LEdemo")

Format

The format is: num [1:10, 1:10, 1:10] 1 1 0 0 0 0 0 0 0 0 ...

Details

This data can be used for testing, demonstrations, or for quickly getting the package up and running, before getting your own data into the proper format.

Source

This data was produced by the author of the package for demonstration purposes and was used in the paper referenced below as the example data.

References

Remmel, T.K. 2022. Extending morphological pattern analysis to 3D voxels. Landscape Ecology 37(2):373-380.

Examples

data(LEdemo)
str(LEdemo)

Performs a morphological segmentation of a binary 3D array

Description

This is the extension of 2D morphological segmentation of binary pixels in a planar raster setting to the 3D domain of voxels. A 3D binary array with 1 (belonging to the feature of interest) and 0 (not belonging to the feature of interest) is the only input required for the mathematical morphological segmentation to proceed. The result is a list object containing the original input data, the categorical segmentation layer, and various summary outputs that may be necessary at later interpretation stages. The algorithm assigns voxels into mutually exclusive categories: outside, mass, skin, crumb, circuit, antenna, bond, void-volume, and void based on their relative positioning and connectivity within the feature of interest.

Usage

morph3d(DATACUBE = NULL, VERBOSE = FALSE, PLOT = FALSE, FINALPLOT = TRUE, PLOTIDS = FALSE)

Arguments

DATACUBE

This is the input 3D data array. The dimensions do not need to be equal, but the data must be binary (0,1) and be of numeric type.

VERBOSE

This is a Boolean flag that turns on | off additional feedback as the code is running. This is generally used for testing and debugging and can easily be set to FALSE with no concern over how the code runs.

PLOT

This is a Boolean flag that turns on | off 3D interactive environment plots for each mutually exclusive morphological class. If these plots are not explicitly required, set this to FALSE, as the plotting is the bottleneck that dramatically slows processing.

FINALPLOT

This is a Boolean flag that turns on | off the 3D interactive environment plot for the final voxel segmentation result. If this is set to FALSE, it can readily be plotted in the future, since the results are saved by the function to a compound list object and the plotting function is supplied with this package.

PLOTIDS

This is a Boolean flag that turns on | off the plotting of unique voxel IDS at the centroids of each voxel during plotting. These can be very useful for identifying specific voxels and associations, but can also clutter the view if they are not expressly required.

Details

Each voxel can belong to only a single 3D morphological class. The concept expands the planar morphological segmentation avaliable in the MSPA software package and establishes corresponding terminology to distinguish the 3D case. The processessing logic is presented and a fully-functional environment allows any binary 3D data to be processed with this engine.

Value

The function returns a LIST object with the following items:

OriginalData

This is the original input 3D data array of 0,1 values.
Graph

This is the network graph object in igraph format for the feature of interest.
VoxelIDs

This is a 3D array with the same dimensions as the input data and contains the unique voxel ID value for each voxel.
ObjectID

If there are multiple disconnected components for the input feature of interest, each component is assigned a unique object ID. This 3D array with the same dimensions as the input data contains those unique object ID values for each voxel.
Morphology

This is a 3D array with the same dimensions as the input data and is a categorical voxel map identifying which morphological class each voxel belongs to. The codes are: 1=outside, 2=mass, 3=skin, 4=crumb, 5=circuit, 6=antenna, 7=bond, 8=void-volume, and 9=void.
Cores

This is a 3D array with the same dimensions as the input data and contains the codes for unique cores (of mass voxels) that may exist within the feature of interest.
ExpCores

This is the same as Cores, but expanded outward to enlarge the volume represented by each core. This is used for internal processing but may be of use or benefit to some, so it is also provided here.
Summary

This is a tabular summary of the morphological segmentation by class. The call name, number of voxels, and the percentage of the total volume is summarized for the actual data provided in the Morphology item.
Egg

This is a temporary output that is used for checking and debugging. It is likely to be eliminated in the future.
Bgrnd

This 3D array identifies the voxels outside the feature of interest, but that are not part of the voids internal to the structure itself.
VOIDvolume

This 3D array identifies the voxels that form the holes, gaps, or voids within the structure.

Note

Current implementation consideres voxels as neighbours if they share a face only (orthogonal neighbours). Expansion to include diagonal neighbours, where voxels share an edge or a point, are being considered. The use of rgl provides functionality to produce interactive 3D plots that greatly facilitate visualization, but dramatically slow the processing as input volumes increase in size. Avoid plotting unless explicitly required. You are able to plot from the stored list object at anytime afterwards too, it is not necessary to plot during the segmentation call.

Author(s)

Tarmo K. Remmel

References

Remmel, T.K. 2022. Extending morphological pattern analysis to 3D voxels. Landscape Ecology 37(2):373-380.

See Also

See Also morph3dplot, morph3dprep

Examples

# SET FINALPLOT=TRUE IF THE INTERACTIVE 3D PLOT IS DESIRED
# THAT CONTAINS THE FINAL SEGMENTATION CATEGORIES
# IF A PLOT FOR EACH CATEGORY IS REQUIRED, SET PLOT=TRUE 
LEdemoOut <- morph3d(LEdemo, PLOT=FALSE, FINALPLOT=FALSE)
str(LEdemoOut)

An internal function that computes the spatial neighbours for voxels. It is an internal function called by morph3d() and not intended to be called on its own.

Description

An internal helper function to compute voxel neighbours in orthogonal 3D space and to return the information in data frame format back to morph3d(), the function that calls this function.

Usage

morph3dlinks(VOLOBJ = NULL, VOXELIDS = NULL, VERBOSE = FALSE)

Arguments

VOLOBJ

This is a 3D array that is larger in all dimensions, within which the actual data array is inset. This ensures that outer margins will be properly processed.

VOXELIDS

This is a 3D array of the unique voxel IDS, which are used to track individual voxels and their connectivity.

VERBOSE

This is a Boolean flag for turning on | off additional feedback during processing.

Details

This internal function simply makes the total length of the morph3d() function shorter.

Value

This function returns an intermediate data frame of voxel neighbours that is subsequently pared down as morph3d() continues.

Note

No additional notes at this time.

Author(s)

Tarmo K. Remmel

References

Remmel, T.K. 2022. Extending morphological pattern analysis to 3D voxels. Landscape Ecology 37(2):373-380.

See Also

See Also morph3d

Examples

# THIS IS AN INTERNAL FUNCITON AND USAGE EXAMPLES ARE NOT NECESSARY

A plot function that converts a 3D array of voxels into an interactive rgl plot.

Description

This plot functionality can be used for any 3D array data that represent voxAels. This functionality is called directly by morph3d() but can be called independently by passing it 3D array data that has been processed by morph3dprep().

Usage

morph3dplot(data = NULL, CELLID = TRUE, LEGEND = FALSE, ORIGTRANSP = TRUE)

Arguments

data

This is the voxel data to be plotted and needs to be processed with morph3dprep() first.

CELLID

A Boolean flag used to control whether the unique voxel IDs are plotted or not.

LEGEND

A Boolean flag that determines whether a legend will be drawn on the ouput interactive plot or not. When this is set to TRUE, plotting is much slower.

ORIGTRANSP

A Boolean flag that is used to set the transparency of original binary input voxel data. It can be used to help produce better visualizations but is not an overly important argument for most.

Details

Output classes are coloured (with varying degrees of transparency to make classes easier to see) as follows. Mass = "green", Skin = "black", Crumb = "brown", Circuit = "orange", Antenna = "pink", Bond = "cornflowerblue", Void-volume = "navy", and Void = "seagreen".

Value

The output is an interactive 3D rgl plot of the voxels supplied as input. Morphological segmentations produced by morph3d() will always have elements drawn in consistent color for ease of interpretation.

Note

No further notes available at this time.

Author(s)

Tarmo K. Remmel

References

Remmel, T.K. 2022. Extending morphological pattern analysis to 3D voxels. Landscape Ecology 37(2):373-380.

See Also

See Also morph3d, morph3dprep

Examples

LEdemoOut <- morph3d(DATACUBE = LEdemo, VERBOSE = FALSE, FINALPLOT = FALSE)
morph2plot <- morph3dprep(INCUBE=LEdemoOut$Morphology, ORIG=FALSE)
# PLOTTING IS TIME INTENSIVE 
morph3dplot(data=morph2plot, CELLID=FALSE, LEGEND=FALSE, ORIGTRANSP=TRUE)

Prepare 3D voxel data for interactive 3D plotting.

Description

Prepares 3D array data for plotting.

Usage

morph3dprep(INCUBE = NULL, ORIG = FALSE)

Arguments

INCUBE

This is the input 3D array of voxels.

ORIG

A Boolean flag to control whether the data is the original input binary data (TRUE), or some other morphological segmentation (FALSE).

Details

No additional details at this time.

Value

The output is...

Note

No additional notes at this time.

Author(s)

Tarmo K. Remmel

References

Remmel, T.K. 2022. Extending morphological pattern analysis to 3D voxels. Landscape Ecology 37(2):373-380.

See Also

See Also morph3d, morph3dplot

Examples

out <- morph3dprep(INCUBE = LEdemo, ORIG = FALSE)
print(out)