Introduction

ChestVolume is an R package designed to process and analyze 3D marker data collected from motion capture systems, particularly for studying chest expansion and respiratory motion. The package provides tools to process the data, adjust marker positions, calculate convex hull volumes for chest segments, and visualize changes in chest expansion over time using both 2D and 3D plots.

Installation

To install ChestVolume from GitHub, use the following commands:

library(devtools)

devtools::install_github(“PKwong86/ChestVolume”)

This will install the package along with its dependencies.

Data Structure and Input Format

The input data should be in the form of a data frame where each marker has three corresponding columns (X, Y, and Z coordinates), and each row represents a different timeframe. The column names should follow the format ‘MXX X’, ‘MXX Y’, and ‘MXX Z’ where ‘MXX’ represents the marker name.

Example Input Data

Each row in the data corresponds to a specific time point, and the columns represent the X, Y, and Z coordinates of markers placed on the chest.

library(ChestVolume)
knitr::kable(head(sample_data[, 1:6]), "pipe")

Core Functions

The ChestVolume package provides several core functions to work with the marker data:

process_marker_data(): This function processes and reshapes the input marker data into a long format with columns for Timeframe, Marker, X, Y, and Z. You can optionally convert the coordinates from millimeters to centimeters by setting the convert_to_cm argument to TRUE.

adj_position(): Adjusts the marker positions by moving them a specified distance toward the center of the chest. This is useful for correcting the slight protrusion of motion capture markers.

calculate_volumes(): Divides the chest into user-defined segments and calculates the convex hull volume for each segment over time.

plot_chest_3d(): Provides a 3D visualization of the chest markers and the convex hulls of the defined chest segments.

plot_2d_volume(): Generates a 2D line plot showing how the chest segment volumes change over time.

Example Workflow

Here’s a step-by-step workflow using ChestVolume to process marker data, adjust the marker positions, calculate chest segment volumes, and visualize the results.

Step 1: Process Marker Data

Load the raw marker data, process it, and optionally convert the units from millimeters to centimeters.

data(sample_data)
processed_data <- process_marker_data(sample_data, convert_to_cm = TRUE)
head(processed_data)
#> # A tibble: 6 × 5
#>   Timeframe Marker     X     Y     Z
#>       <int> <chr>  <dbl> <dbl> <dbl>
#> 1         1 M01     1.88  80.4  91.4
#> 2         1 M02     7.25  76.0  74.8
#> 3         1 M03     8.11  74.7  65.9
#> 4         1 M04    -1.83  85.6  87.9
#> 5         1 M05     3.90  81.3  72.9
#> 6         1 M06     4.31  79.3  64.9

Step 2: Adjust Marker Positions

Use the adj_position() function to adjust the marker positions by a set distance (e.g., 1 cm) toward the chest surface.

# Adjust the marker positions by moving them 1 cm toward the chest center
adjusted_data <- adj_position(processed_data, distance = 1)
head(adjusted_data)
#> # A tibble: 6 × 5
#>   Timeframe Marker     X     Y     Z
#>       <int> <chr>  <dbl> <dbl> <dbl>
#> 1         1 M01     1.58  79.9  90.6
#> 2         1 M02     6.36  75.6  75.1
#> 3         1 M03     7.43  74.5  66.6
#> 4         1 M04    -1.91  84.8  87.3
#> 5         1 M05     3.36  80.6  73.3
#> 6         1 M06     3.87  78.9  65.6

#Step 3: Define Chest Segments and Calculate Volumes Define the chest segments based on marker names and calculate the convex hull volumes for each segment over time.

segments <- list(
  upper_left = c("M01", "M02", "M04", "M05","M07", "M08","M10", "M11")
)
volumes<- calculate_volumes(adjusted_data, segments)
head(volumes)
#> # A tibble: 6 × 3
#>   Timeframe Segment    Volume
#>       <int> <chr>       <dbl>
#> 1         1 upper_left  1759.
#> 2         2 upper_left  1759.
#> 3         3 upper_left  1759.
#> 4         4 upper_left  1759.
#> 5         5 upper_left  1759.
#> 6         6 upper_left  1759.

Step 4: Visualize Chest Expansion in 3D

Use the plot_chest_3d() function to create a 3D plot of the chest markers and their convex hull volumes.

#Step 5: Plot Volume Changes Over Time Generate a 2D line plot showing how the chest segment volumes change over time using plot_2d_volume().

plot_2d_volume(volumes, 'Segment')

segments <- read_segment_definitions(system.file("extdata", "segment_def.xlsx", package="ChestVolume"))
head(segments)
#> $`Segment Name`
#>  [1] "Marker 1"  "Marker 2"  "Marker 3"  "Marker 4"  "Marker 5"  "Marker 6" 
#>  [7] "Marker 7"  "Marker 8"  "Marker 9"  "Marker 10" "Marker 11" "Marker 12"
#> 
#> $UL
#>  [1] "M01" "M02" "M04" "M05" "M07" "M08" "M10" "M11" "M13" "M14" "M16" "M17"
#> 
#> $UR
#>  [1] "M16" "M17" "M19" "M20" "M22" "M23" "M25" "M26" "M28" "M29" "M01" "M02"
#> 
#> $LL
#>  [1] "M02" "M03" "M05" "M06" "M08" "M09" "M11" "M12" "M14" "M15" "M17" "M18"
#> 
#> $LR
#>  [1] "M17" "M18" "M20" "M21" "M23" "M24" "M26" "M27" "M29" "M30" "M02" "M03"