The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

ChestVolume

library(ChestVolume)

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")
M19 X M19 Y M19 Z M10 X M10 Y M10 Z
-108.966 664.901 974.120 -158.588 854.272 881.284
-108.909 664.922 974.164 -158.550 854.293 881.271
-108.852 664.944 974.205 -158.517 854.316 881.266
-108.794 664.970 974.241 -158.489 854.342 881.271
-108.736 664.999 974.269 -158.467 854.368 881.285
-108.681 665.027 974.286 -158.446 854.392 881.302

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

Additional Features

Custom Segment Definitions You can define custom chest segments by uploading an Excel file that specifies which markers belong to which segment. Use the read_segment_definitions() function to read the segment definitions from the file.

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"

Shiny App

For users who prefer a graphical user interface, ChestVolume includes a Shiny app. This app allows you to interact with the data visually, upload datasets, define segments, and calculate and visualize chest expansion.

Access the Shiny app online: https://waihangkwong.shinyapps.io/Lung_volumn/

Conclusion

The ChestVolume package provides a comprehensive set of tools for analyzing chest expansion using 3D motion capture data. By allowing users to process, adjust, and visualize chest volume data, the package supports advanced respiratory health assessments and research.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.