Type:	Package
Title:	Analysis of Elliptical Tubes Under the Relative Curvature Condition
Version:	1.2.0
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." 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
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-05-26 11:32:42 UTC; mohsentaheri
Repository:	CRAN
Date/Publication:	2025-06-05 06:10:02 UTC

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,
  add = FALSE
)

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
 plot_Elliptical_Tube(tube = tube,plot_frames = FALSE,
                      plot_skeletal_sheet = TRUE,
                      plot_r_project = FALSE,
                      plot_r_max = FALSE,add = FALSE)

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
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)
}

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
plot_Elliptical_Tube(tube = intrinsic_mean,
                     plot_frames = FALSE,
                     plot_skeletal_sheet = FALSE,
                     plot_r_project = FALSE,
                     plot_r_max = FALSE,
                     add = FALSE)

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

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
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)
}

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
plot_Elliptical_Tube(tube = nonIntrinsic_mean,
                     plot_frames = FALSE,
                     plot_skeletal_sheet = FALSE,
                     plot_r_project = FALSE,
                     plot_r_max = FALSE,
                     add = FALSE)

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

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")
plot_Elliptical_Tube(tube = colon3D,
                     plot_frames = FALSE,
                     add=FALSE)

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<-3
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
rgl::open3d()
for (i in 1:numberOfSimulation) {
  plot_Elliptical_Tube(tube = random_Tubes[[i]],
                       plot_frames = FALSE,
                       plot_skeletal_sheet = FALSE,
                       plot_r_project = FALSE,
                       plot_r_max = FALSE,
                       add = TRUE)
}

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

quad_mesh<-tube_Surface_Mesh(tube = ETRep::tube_B, 
                             meshType = "quadrilateral", 
                             plotMesh = TRUE, 
                             decorate = TRUE, 
                             color = "orange")
tri_mesh<-tube_Surface_Mesh(tube = ETRep::tube_B, 
                            meshType = "triangular", 
                            plotMesh = TRUE, 
                            decorate = TRUE, 
                            color = "green")