Type: Package
Title: Analysis of Elliptical Tubes Under the Relative Curvature Condition
Version: 1.2.1
Maintainer: Mohsen Taheri Shalmani <MohsenTaheriShalmani@gmail.com>
Description: Analysis of elliptical tubes with applications in biological modeling. The package is based on the references: Taheri, M., Pizer, S. M., & Schulz, J. (2024) "The Mean Shape under the Relative Curvature Condition." Journal of Computational and Graphical Statistics <doi:10.1080/10618600.2025.2535600> and arXiv <doi:10.48550/arXiv.2404.01043>. Mohsen Taheri Shalmani (2024) "Shape Statistics via Skeletal Structures", PhD Thesis, University of Stavanger, Norway <doi:10.13140/RG.2.2.34500.23685>. Key features include constructing discrete elliptical tubes, calculating transformations, validating structures under the Relative Curvature Condition (RCC), computing means, and generating simulations. Supports intrinsic and non-intrinsic mean calculations and transformations, size estimation, plotting, and random sample generation based on a reference tube. The intrinsic approach relies on the interior path of the original non-convex space, incorporating the RCC, while the non-intrinsic approach uses a basic robotic arm transformation that disregards the RCC.
License: MIT + file LICENSE
URL: https://github.com/MohsenTaheriShalmani/Elliptical_Tubes
Depends: R (≥ 4.0.0)
Author: Mohsen Taheri Shalmani ORCID iD [aut, cre], Jörn Schulz [aut], Stephen M. Pizer [aut]
Encoding: UTF-8
LazyData: true
Imports: rgl, shapes, Morpho, matlib, RSpincalc, rotations, Rvcg, fields, truncnorm, htmlwidgets
RoxygenNote: 7.3.3
NeedsCompilation: no
Packaged: 2025-09-27 09:40:48 UTC; mohsentaheri
Repository: CRAN
Date/Publication: 2025-09-27 10:00:02 UTC

Open an rgl device with fallback to WebGL

Description

This function tries to open a native rgl window. If that fails (e.g. on macOS without OpenGL) it falls back to an off-screen device suitable for rendering with rglwidget().

Usage

.etrep_open3d(show_widget = TRUE, ...)

Arguments

show_widget

logical; if TRUE and native OpenGL is not available, a message is displayed suggesting to use etrep_show3d().

...

additional arguments passed to [rgl::open3d()].

Value

Device ID returned by [rgl::open3d()].


Display current rgl scene in the browser

Description

Saves the current rgl scene to a temporary HTML file and opens it in the system's default browser.

Usage

.etrep_show3d(width = 800, height = 600)

Arguments

width, height

size of the viewer in pixels.

Value

The path to the HTML file (invisible).


Package startup hook

Description

This special function is called automatically when the ETRep package is loaded. It ensures that 'rgl' uses the off-screen WebGL device ('useNULL = TRUE') on macOS and other headless environments, so that package installation and examples do not fail with an OpenGL error.

Usage

.onLoad(libname, pkgname)

Arguments

libname

Character string; the path to the package library.

pkgname

Character string; the name of the package.

If the user has not already set 'options(rgl.useNULL)', this function sets it to 'TRUE' to suppress the typical warning: "rgl.init failed, will use the null device".


Check the Legality of an Elliptical Tube (ETRep)

Description

Checks the validity of a given ETRep based on the Relative Curvature Condition (RCC) and principal radii such that forall i a_i>b_i.

Usage

check_Tube_Legality(tube)

Arguments

tube

List containing ETRep details.

Value

Logical value: TRUE if valid, FALSE otherwise.

References

Taheri, M., Pizer, S. M., & Schulz, J. (2024). "The Mean Shape under the Relative Curvature Condition." arXiv. doi:10.48550/arXiv.2404.01043

Taheri Shalmani, M. (2024). "Shape Statistics via Skeletal Structures." University of Stavanger. doi:10.13140/RG.2.2.34500.23685

Examples

# Load tube
data("colon3D")
check_Tube_Legality(tube = colon3D)

Data

Description

A colon sample as an elliptical tube.

Usage

colon3D

Format

A list containing the information of an e-tube

Source

Generated and stored in the package's 'data/' folder.


Create a Discrete Elliptical Tube (ETRep)

Description

Constructs a discrete elliptical tube (ETRep) based on specified parameters.

Usage

create_Elliptical_Tube(
  numberOfFrames,
  method,
  materialFramesBasedOnParents = NA,
  initialFrame = diag(3),
  initialPoint = c(0, 0, 0),
  EulerAngles_Matrix = NA,
  ellipseResolution = 10,
  ellipseRadii_a,
  ellipseRadii_b,
  connectionsLengths,
  plotting = TRUE
)

Arguments

numberOfFrames

Integer, specifies the number of consecutive material frames.

method

String, either "basedOnEulerAngles" or "basedOnMaterialFrames", defines the material frames method.

materialFramesBasedOnParents

Array (3 x 3 x numberOfFrames) with pre-defined material frames.

initialFrame

Matrix 3 x 3 as the initial frame

initialPoint

Real vector with three elemets as the initial point

EulerAngles_Matrix

Matrix of dimensions numberOfFrames x 3 with Euler angles to define material frames.

ellipseResolution

Integer, resolution of elliptical cross-sections (default is 10).

ellipseRadii_a

Numeric vector for the primary radii of cross-sections.

ellipseRadii_b

Numeric vector for the secondary radii of cross-sections.

connectionsLengths

Numeric vector for lengths of spinal connection vectors.

plotting

Logical, enables plotting of the ETRep (default is TRUE).

Value

List containing tube details (orientation, radii, connection lengths, boundary points, etc.).

References

Taheri, M., Pizer, S. M., & Schulz, J. (2024). "The Mean Shape under the Relative Curvature Condition." arXiv. doi:10.48550/arXiv.2404.01043

Taheri Shalmani, M. (2024). "Shape Statistics via Skeletal Structures." University of Stavanger. doi:10.13140/RG.2.2.34500.23685

Examples

numberOfFrames<-15
EulerAngles_alpha<-c(rep(0,numberOfFrames))
EulerAngles_beta<-c(rep(-pi/20,numberOfFrames))
EulerAngles_gamma<-c(rep(0,numberOfFrames))
EulerAngles_Matrix<-cbind(EulerAngles_alpha,
                          EulerAngles_beta,
                          EulerAngles_gamma)
tube <- create_Elliptical_Tube(numberOfFrames = numberOfFrames,
                               method = "basedOnEulerAngles",
                               EulerAngles_Matrix = EulerAngles_Matrix,
                               ellipseResolution = 10,
                               ellipseRadii_a = rep(3, numberOfFrames),
                               ellipseRadii_b = rep(2, numberOfFrames),
                               connectionsLengths = rep(4, numberOfFrames),
                               plotting = FALSE)
# Plotting
## Not run: 
 plot_Elliptical_Tube(tube = tube,plot_frames = FALSE,
                      plot_skeletal_sheet = TRUE,
                      plot_r_project = FALSE,
                      plot_r_max = FALSE,add = FALSE)
 
## End(Not run)

Convert an ETRep to a Matrix in the Convex Transformed Space.

Description

Convert an ETRep to a Matrix in the Convex Transformed Space.

Usage

elliptical_Tube_Euclideanization(tube)

Arguments

tube

A list containing the details of the ETRep.

Value

An n*6 matrix, where n is the number of spinal points, representing the ETRep in the transformed Euclidean convex space.

Examples

#Example
# Load tube
data("tube_A")
Euclideanized_Tube<- elliptical_Tube_Euclideanization(tube = tube_A)


Calculating the intrinsic distance between two ETReps

Description

Calculating the intrinsic distance between two ETReps

Usage

intrinsic_Distance_Between2tubes(tube1, tube2)

Arguments

tube1

List containing ETRep details.

tube2

List containing ETRep details.

Value

Numeric

References

Taheri, M., Pizer, S. M., & Schulz, J. (2024). "The Mean Shape under the Relative Curvature Condition." arXiv. doi:10.48550/arXiv.2404.01043

Taheri Shalmani, M. (2024). "Shape Statistics via Skeletal Structures." University of Stavanger. doi:10.13140/RG.2.2.34500.23685

Examples

# Load tubes
data("tube_A")
data("tube_B")
intrinsic_Distance_Between2tubes(tube1 = tube_A,tube2 = tube_B)

Intrinsic Transformation Between Two ETReps

Description

Performs an intrinsic transformation from one ETRep to another, preserving essential e-tube properties such as the Relative Curvature Condition (RCC) while avoiding local self-intersections.

Usage

intrinsic_Transformation_Elliptical_Tubes(
  tube1,
  tube2,
  type = "sizeAndShapeAnalysis",
  numberOfSteps = 5,
  plotting = TRUE,
  colorBoundary = "blue"
)

Arguments

tube1

List containing details of the first ETRep.

tube2

List containing details of the second ETRep.

type

String defining the type of analysis as sizeAndShapeAnalysis or shapeAnalysis

numberOfSteps

Integer, number of transformation steps.

plotting

Logical, enables visualization during transformation (default is TRUE).

colorBoundary

String defining the color of the e-tube

Value

List containing intermediate ETReps.

References

Taheri, M., Pizer, S. M., & Schulz, J. (2024). "The Mean Shape under the Relative Curvature Condition." arXiv. doi:10.48550/arXiv.2404.01043

Taheri Shalmani, M. (2024). "Shape Statistics via Skeletal Structures." University of Stavanger. doi:10.13140/RG.2.2.34500.23685

Examples


# Load tubes
data("tube_A")
data("tube_B")
numberOfSteps <- 10
transformation_Tubes<-
  intrinsic_Transformation_Elliptical_Tubes(
    tube1 = tube_A,tube2 = tube_B,
    numberOfSteps = numberOfSteps,
    plotting = FALSE)
# Plotting
## Not run: 
for (i in 1:length(transformation_Tubes)) {
  plot_Elliptical_Tube(tube = transformation_Tubes[[i]],
  plot_frames = FALSE,plot_skeletal_sheet = FALSE
  ,plot_r_project = FALSE,
  plot_r_max = FALSE,
  add = FALSE)
}
##
## End(Not run)


Calculate Intrinsic Mean of ETReps

Description

Computes the intrinsic mean of a set of ETReps. The computation involves transforming the non-convex hypertrumpet space into a convex space, calculating the mean in this transformed space, and mapping the result back to the original hypertrumpet space.

Usage

intrinsic_mean_tube(tubes, type = "sizeAndShapeAnalysis", plotting = TRUE)

Arguments

tubes

List of ETReps.

type

String, "ShapeAnalysis" or "sizeAndShapeAnalysis" (default is "sizeAndShapeAnalysis").

plotting

Logical, enables visualization of the mean (default is TRUE).

Value

List representing the mean ETRep.

References

Taheri, M., Pizer, S. M., & Schulz, J. (2024). "The Mean Shape under the Relative Curvature Condition." arXiv. doi:10.48550/arXiv.2404.01043

Taheri Shalmani, M. (2024). "Shape Statistics via Skeletal Structures." University of Stavanger. doi:10.13140/RG.2.2.34500.23685

Examples

#Example 1
# Load tubes
data("tube_A")
data("tube_B")
intrinsic_mean<-
  intrinsic_mean_tube(tubes = list(tube_A,tube_B),
                      plotting = FALSE)
# Plotting
## Not run: 
plot_Elliptical_Tube(tube = intrinsic_mean,
                     plot_frames = FALSE,
                     plot_skeletal_sheet = FALSE,
                     plot_r_project = FALSE,
                     plot_r_max = FALSE,
                     add = FALSE)
 
## End(Not run)

#Example 2
data("simulatedColons")
intrinsic_mean<-
  intrinsic_mean_tube(tubes = simulatedColons,
                      plotting = FALSE)
# Plotting
## Not run: 
plot_Elliptical_Tube(tube = intrinsic_mean,
                     plot_frames = FALSE,
                     plot_skeletal_sheet = FALSE,
                     plot_r_project = FALSE,
                     plot_r_max = FALSE,
                     add = FALSE)
 
## End(Not run)

Calculating the non-intrinsic distance between two ETReps

Description

Calculating the non-intrinsic distance between two ETReps

Usage

nonIntrinsic_Distance_Between2tubes(tube1, tube2)

Arguments

tube1

List containing ETRep details.

tube2

List containing ETRep details.

Value

Numeric

References

Taheri, M., Pizer, S. M., & Schulz, J. (2024). "The Mean Shape under the Relative Curvature Condition." arXiv. doi:10.48550/arXiv.2404.01043

Taheri Shalmani, M. (2024). "Shape Statistics via Skeletal Structures." University of Stavanger. doi:10.13140/RG.2.2.34500.23685

Examples

# Load tubes
data("tube_A")
data("tube_B")
intrinsic_Distance_Between2tubes(tube1 = tube_A,tube2 = tube_B)

Non-Intrinsic Transformation Between Two ETReps

Description

Performs a non-intrinsic transformation from one ETRep to another. This approach is inspired by robotic arm transformations and does not account for the Relative Curvature Condition (RCC).

Usage

nonIntrinsic_Transformation_Elliptical_Tubes(
  tube1,
  tube2,
  type = "sizeAndShapeAnalysis",
  numberOfSteps = 4,
  plotting = TRUE,
  colorBoundary = "blue",
  add = FALSE
)

Arguments

tube1

List containing details of the first ETRep.

tube2

List containing details of the second ETRep.

type

String defining the type of analysis as sizeAndShapeAnalysis or shapeAnalysis

numberOfSteps

Integer, number of transformation steps.

plotting

Logical, enables visualization during transformation (default is TRUE).

colorBoundary

String defining the color of the e-tube

add

Logical, enables overlay plotting

Value

List containing intermediate ETReps.

References

Taheri, M., Pizer, S. M., & Schulz, J. (2024). "The Mean Shape under the Relative Curvature Condition." arXiv. doi:10.48550/arXiv.2404.01043

Taheri Shalmani, M. (2024). "Shape Statistics via Skeletal Structures." University of Stavanger. doi:10.13140/RG.2.2.34500.23685

Examples


# Load tubes
data("tube_A")
data("tube_B")
numberOfSteps <- 10
transformation_Tubes<-
  nonIntrinsic_Transformation_Elliptical_Tubes(
    tube1 = tube_A,tube2 = tube_B,
    numberOfSteps = numberOfSteps,
    plotting = FALSE)
# Plotting
## Not run: 
for (i in 1:length(transformation_Tubes)) {
  plot_Elliptical_Tube(tube = transformation_Tubes[[i]],
  plot_frames = FALSE,plot_skeletal_sheet = FALSE
  ,plot_r_project = FALSE,
  plot_r_max = FALSE,
  add = FALSE)
}
 
## End(Not run)


Compute Non-Intrinsic Mean of ETReps

Description

Calculates the non-intrinsic mean of a set of ETReps. This method utilizes a non-intrinsic distance metric based on robotic arm non-intrinsic transformations.

Usage

nonIntrinsic_mean_tube(tubes, type = "sizeAndShapeAnalysis", plotting = TRUE)

Arguments

tubes

List of ETReps.

type

String, "ShapeAnalysis" or "sizeAndShapeAnalysis" (default is "sizeAndShapeAnalysis").

plotting

Logical, enables visualization of the mean (default is TRUE).

Value

List representing the mean ETRep.

Examples

#Example 1
# Load tubes
data("tube_A")
data("tube_B")
nonIntrinsic_mean<-
  nonIntrinsic_mean_tube(tubes = list(tube_A,tube_B),
                         plotting = FALSE)
# Plotting
## Not run: 
plot_Elliptical_Tube(tube = nonIntrinsic_mean,
                     plot_frames = FALSE,
                     plot_skeletal_sheet = FALSE,
                     plot_r_project = FALSE,
                     plot_r_max = FALSE,
                     add = FALSE)
 
## End(Not run)

#Example 2
data("simulatedColons")
nonIntrinsic_mean<-
  nonIntrinsic_mean_tube(tubes = simulatedColons,
                         plotting = FALSE)
# Plotting
## Not run: 
plot_Elliptical_Tube(tube = nonIntrinsic_mean,
                     plot_frames = FALSE,
                     plot_skeletal_sheet = FALSE,
                     plot_r_project = FALSE,
                     plot_r_max = FALSE,
                     add = FALSE)
 
## End(Not run)

Plot an Elliptical Tube (ETRep)

Description

Plots a given ETRep with options for boundary, material frames, and projection visualization.

Usage

plot_Elliptical_Tube(
  tube,
  plot_boundary = TRUE,
  plot_r_max = FALSE,
  plot_r_project = TRUE,
  plot_frames = TRUE,
  frameScaling = NA,
  plot_spine = TRUE,
  plot_normal_vec = FALSE,
  plot_skeletal_sheet = TRUE,
  decorate = TRUE,
  colSkeletalSheet = "blue",
  colorBoundary = "blue",
  add = FALSE
)

Arguments

tube

List containing ETRep details.

plot_boundary

Logical, enables plotting of the boundary (default is TRUE).

plot_r_max

Logical, enables plotting of max projection size (default is FALSE).

plot_r_project

Logical, enables plotting of projection along normals (default is TRUE).

plot_frames

Logical, enables plotting of the material frames (default is TRUE).

frameScaling

Numeric, scale factor for frames.

plot_spine

Logical, enables plotting of the spine.

plot_normal_vec

Logical, enables plotting of the normals.

plot_skeletal_sheet

Logical, enables plotting of the surface skeleton.

decorate

Logical, enables decorate the plot

colSkeletalSheet

String, defining the color of the surface skeleton

colorBoundary

String, defining the color of the e-tube

add

Logical, enables overlay plotting

Value

Graphical output.

Examples

# Load tube
data("colon3D")
## Not run: 
plot_Elliptical_Tube(tube = colon3D,
                     plot_frames = FALSE)
 
## End(Not run)

Simulate Random Elliptical Tubes (ETReps)

Description

Generates random samples of ETReps based on a reference tube with added variation.

Usage

simulate_etube(
  referenceTube,
  numberOfSimulation,
  sd_v = 10^-10,
  sd_psi = 10^-10,
  sd_x = 10^-10,
  sd_a = 10^-10,
  sd_b = 10^-10,
  rangeSdScale = c(1, 2),
  plotting = TRUE
)

Arguments

referenceTube

List containing ETRep information as the reference.

numberOfSimulation

Integer, number of random samples.

sd_v

Standard deviations for various parameters.

sd_psi

Standard deviations for various parameters.

sd_x

Standard deviations for various parameters.

sd_a

Standard deviations for various parameters.

sd_b

Standard deviations for various parameters.

rangeSdScale

Numeric range for random scaling.

plotting

Logical, enables visualization of samples (default is FALSE).

Value

List of random ETReps.

References

Taheri, M., Pizer, S. M., & Schulz, J. (2024). "The Mean Shape under the Relative Curvature Condition." arXiv. doi:10.48550/arXiv.2404.01043

Taheri Shalmani, M. (2024). "Shape Statistics via Skeletal Structures." University of Stavanger. doi:10.13140/RG.2.2.34500.23685

Examples


# Load tube
data("colon3D")
#Set Parameters
sd_v<-sd_psi<-1e-03
sd_x<-sd_a<-sd_b<-1e-04
numberOfSimulation<-4
random_Tubes<-
  simulate_etube(referenceTube = colon3D,
                 numberOfSimulation = numberOfSimulation,
                 sd_v = sd_v,
                 sd_psi = sd_psi,
                 sd_x = sd_x,
                 sd_a = sd_a,
                 sd_b = sd_b,
                 rangeSdScale = c(1, 2),
                 plotting = FALSE)
# Plotting
## Not run: 
plot_Elliptical_Tube(random_Tubes[[1]], add = FALSE)
plot_Elliptical_Tube(random_Tubes[[2]], add = TRUE)
plot_Elliptical_Tube(random_Tubes[[3]], add = TRUE)
plot_Elliptical_Tube(random_Tubes[[4]], add = TRUE)
 
## End(Not run)


Data

Description

Simulated samples of e-tubes, modeled after a reference structure resembling a colon.

Usage

simulatedColons

Format

Five simulated samples of elliptical tubes, modeled after a reference structure resembling a colon.

Source

Generated and stored in the package's 'data/' folder.


Data

Description

A tube with 204 elliptical cross-sections.

Usage

tube_A

Format

A list containing the information of an e-tube with 204 elliptical cross-sections

Source

Generated and stored in the package's 'data/' folder.


Data

Description

A tube with 204 elliptical cross-sections.

Usage

tube_B

Format

A list containing the information of an e-tube with 204 elliptical cross-sections

Source

Generated and stored in the package's 'data/' folder.


Create surface mesh of a tube

Description

Create surface mesh of a tube

Usage

tube_Surface_Mesh(
  tube,
  meshType = "quadrilateral",
  plotMesh = TRUE,
  color = "blue",
  decorate = TRUE
)

Arguments

tube

List containing ETRep details.

meshType

String, either "quadrilateral" or "triangular" definig the type of mesh.

plotMesh

Logical, enables plotting of the mesh (default is TRUE).

color

String, defining the color of the mesh (default is 'blue').

decorate

Logical, enables decorating the plot (default is TRUE).

Value

An object from rgl::mesh3d class

Examples

## Not run: 
quad_mesh<-tube_Surface_Mesh(tube = ETRep::tube_B, 
                             meshType = "quadrilateral", 
                             plotMesh = TRUE, 
                             decorate = TRUE, 
                             color = "orange")
# draw wireframe of the mesh
rgl::wire3d(quad_mesh, color = "black", lwd = 1)   # add wireframe
# Display in browser
ETRep:::.etrep_show3d(width = 800, height = 600)

tri_mesh<-tube_Surface_Mesh(tube = ETRep::tube_B, 
                            meshType = "triangular", 
                            plotMesh = TRUE, 
                            decorate = TRUE, 
                            color = "green")
# draw wireframe of the mesh
rgl::wire3d(tri_mesh, color = "black", lwd = 1)   # add wireframe
# Display in browser
ETRep:::.etrep_show3d(width = 800, height = 600)
 
## End(Not run)