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 [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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)