Title:	Estimate the Chest Volume with Markers Data
Version:	1.0.1
Maintainer:	Wai-Hang Kwong <wai-hang.kwong@polyu.edu.hk>
Description:	Provides tools to process and analyze chest expansion using 3D marker data from motion capture systems. Includes functions for data processing, marker position adjustment, volume calculation using convex hulls, and visualization in 2D and 3D. Barber et al. (1996) <doi:10.1145/235815.235821>. TAMIYA Hiroyuki et al. (2021) <doi:10.1038/s41598-021-01033-8>.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.2
Depends:	R (≥ 4.0.0)
Imports:	readxl, dplyr, tidyr, geometry, ggplot2, plotly
LazyData:	true
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2025-01-24 04:36:17 UTC; whkwong
Author:	Wai-Hang Kwong [aut, cre]
Repository:	CRAN
Date/Publication:	2025-01-24 04:50:01 UTC

Example Chest Segment Definition

Description

This dataset defines chest segmentations using 3D markers. It is a list containing five elements: the first element is a vector of marker names, and the remaining four elements define markers assigned to four chest segments: UL (Upper Left), UR (Upper Right), LL (Lower Left), and LR (Lower Right).

Usage

Segment_example

Format

A list with 5 elements:

Marker Names

A character vector of marker names.

UL

A character vector of marker names included in the upper left (UL) chest segment.

UR

A character vector of marker names included in the upper right (UR) chest segment.

LL

A character vector of marker names included in the lower left (LL) chest segment.

LR

A character vector of marker names included in the lower right (LR) chest segment.

Details

This dataset is used to demonstrate how markers can be grouped into segments based on their positions on the chest. The segmentation divides the chest into four quadrants: UL (Upper Left), UR (Upper Right), LL (Lower Left), and LR (Lower Right).

Examples

# Load the dataset
data(Segment_example)

# View the structure of the dataset
str(Segment_example)

# Extract the marker names
marker_names <- Segment_example[[1]]

# Extract markers for the upper left (UL) segment
UL_markers <- Segment_example$UL

Adjust Marker Positions Towards Center

Description

Adjusts the positions of markers by moving them towards a specified center position within each timeframe by a specified distance. The center (centroid) can be determined by one of two methods:

Usage

adj_position(data, distance = 1, centroid = "Average")

Arguments

Details

1. "average" (default): The centroid is computed as the mean of all marker coordinates in each timeframe.

2. "convex hull": The centroid is computed using a convex hull-based approach, representing a geometrically derived center.

When centroid = "average", the centroid is simply the mean of X, Y, and Z for all markers within each timeframe. When centroid = "convex hull", the centroid is computed using a convex hull-based method to identify a more geometrically relevant center.

Value

A data frame of the same dimensions as data, containing the adjusted marker coordinates.

Examples

data("sample_data")
reformat_data <- reformat_marker_data(head(sample_data))

# Using the average centroid (default)
adjusted_data_avg <- adj_position(reformat_data, distance = 1, centroid = "average")
head(adjusted_data_avg)

# Using the convex hull centroid
adjusted_data_ch <- adj_position(reformat_data, distance = 1, centroid = "convex hull")

Calculate Segment Volumes Over Time

Description

Calculates the volumes of specified segments over time using convex hulls.

Usage

calculate_volumes(data, segments)

Arguments

Details

Coordinates should be in centimeters to ensure correct volume units (cm³).

Value

A data frame with columns 'Timeframe', 'Segment', 'Volume'.

Examples

# Define segments (e.g., quadrants of the chest)
segments <- list(
  UL = c("M01", "M02", "M03", "M04"),
  UR = c("M05", "M06", "M07", "M08")
)

# Assume 'adjusted_data' is the data frame with adjusted marker positions in cm
data('sample_data')
reformat_data <- reformat_marker_data(head(sample_data))
adjusted_data <- adj_position(reformat_data)
volumes_df <- calculate_volumes(adjusted_data, segments)
head(volumes_df)

Plot Volume Changes by Segment Over Time

Description

This function generates a ggplot to display the volume changes by segment over time. It creates a line plot with each segment's volume on the y-axis and the timeframe on the x-axis.

Usage

plot_2d_volume(
  volume_data,
  segment_names = "Segment",
  title = "Volume Change by Segment"
)

Arguments

Value

A ggplot object showing volume changes by segment over time.

Examples

# Example usage with random volume data
set.seed(123)
volume_data <- data.frame(
  Timeframe = 1:100,
  Volume = runif(100, min = 100, max = 150),
  Segment = 'UL'
)

plot_2d_volume(volume_data, segment_names = 'Segment')

Plot 3D Chest Markers with Highlighted Segment and Convex Hull

Description

Generates a 3D plot of chest markers with the selected segment highlighted, including the convex hull mesh of the selected segment.

Usage

plot_chest_3d(
  data,
  segments,
  selected_segment,
  timeframe = NULL,
  point_size = 5,
  highlight_color = "red",
  marker_color = "blue"
)

Arguments

Details

The function plots all markers at the specified timeframe, highlighting the markers in the selected segment and overlaying the convex hull mesh of the selected segment. The plot is interactive, allowing for rotation and zooming.

Value

A plotly object representing the 3D plot.

Examples

# Example input data (replace with your actual data)
data(sample_data)
df<-reformat_marker_data(head(sample_data))
df_a <- adj_position(df)
# Define segments
segments <- list(
  UL = c("M01", "M02", "M03", "M04")
)
# Plot the 'UL' segment at timeframe 1
plot <- plot_chest_3d(df_a, segments, selected_segment = "UL", timeframe = 1)
# Display the plot
plot

Deprecated: Process Marker Data

Description

This function is deprecated. Please use reformat_marker_data instead.

Usage

process_marker_data(data, convert_to_cm = FALSE)

Arguments

Value

A data frame of the same format as reformat_marker_data().

Examples

data("sample_data")
# Using the old function will show a warning and call reformat_marker_data()
processed_data <- process_marker_data(head(sample_data), convert_to_cm = TRUE)
head(processed_data)

Read Segment Definitions from Excel File

Description

Reads an Excel file defining the markers in each segment and creates a list suitable for use with plot_chest_3d and calculate_segment_volumes functions.

Usage

read_segment_definitions(filepath)

Arguments

Details

The Excel file should have a specific format:

• Each row represents a segment.

• The first column contains the segment names.

• Subsequent columns contain the marker names belonging to each segment.

Missing marker entries can be left blank or filled with NA.

Value

A named list where each element is a character vector of marker names defining a segment.

Examples

# 'segment_def.xlsx' is the Excel file with segment definitions
path <- system.file("extdata", "segment_def.xlsx", package="ChestVolume")
segments <- read_segment_definitions(path)
head(segments)

reformat and Sort Marker Data for All Time Frames

Description

reformat the input dataset by sorting marker columns based on marker names and reformats it into a long format with columns 'Timeframe', 'Marker', 'X', 'Y', 'Z'. Adds a Timeframe column corresponding to each row (time frame) in the original data.

Usage

reformat_marker_data(data, convert_to_cm = TRUE)

Arguments

Details

The function reshapes the wide-format data into a long format suitable for analysis, adding a Timeframe column that corresponds to each time frame. Optionally converts units to centimeters.

Value

A data frame with columns 'Timeframe', 'Marker', 'X', 'Y', 'Z', sorted by Timeframe and Marker.

Examples

data(sample_data)
reformat_data <- reformat_marker_data(head(sample_data), convert_to_cm = TRUE)
head(reformat_data)

Sample 3D Motion Capture Data for Chest Expansion Analysis

Description

This dataset contains 3D marker coordinate data collected from motion capture systems for chest expansion analysis. It includes 2309 time frames and 30 markers. Each marker has three coordinates: X, Y, and Z, representing its position in 3D space.

Usage

sample_data

Format

A data frame with 2309 rows and 90 variables (30 markers, each with X, Y, Z coordinates):

M01 X

X-coordinate of marker M01

M01 Y

Y-coordinate of marker M01

M01 Z

Z-coordinate of marker M01

M02 X

X-coordinate of marker M02

M02 Y

Y-coordinate of marker M02

M02 Z

Z-coordinate of marker M02

M03 X

X-coordinate of marker M03

M03 Y

Y-coordinate of marker M03

M03 Z

Z-coordinate of marker M03

M04 X

X-coordinate of marker M04

M04 Y

Y-coordinate of marker M04

M04 Z

Z-coordinate of marker M04

M05 X

X-coordinate of marker M05

M05 Y

Y-coordinate of marker M05

M05 Z

Z-coordinate of marker M05

M06 X

X-coordinate of marker M06

M06 Y

Y-coordinate of marker M06

M06 Z

Z-coordinate of marker M06

M07 X

X-coordinate of marker M07

M07 Y

Y-coordinate of marker M07

M07 Z

Z-coordinate of marker M07

M08 X

X-coordinate of marker M08

M08 Y

Y-coordinate of marker M08

M08 Z

Z-coordinate of marker M08

M09 X

X-coordinate of marker M09

M09 Y

Y-coordinate of marker M09

M09 Z

Z-coordinate of marker M09

M10 X

X-coordinate of marker M10

M10 Y

Y-coordinate of marker M10

M10 Z

Z-coordinate of marker M10

M11 X

X-coordinate of marker M11

M11 Y

Y-coordinate of marker M11

M11 Z

Z-coordinate of marker M11

M12 X

X-coordinate of marker M12

M12 Y

Y-coordinate of marker M12

M12 Z

Z-coordinate of marker M12

M13 X

X-coordinate of marker M13

M13 Y

Y-coordinate of marker M13

M13 Z

Z-coordinate of marker M13

M14 X

X-coordinate of marker M14

M14 Y

Y-coordinate of marker M14

M14 Z

Z-coordinate of marker M14

M15 X

X-coordinate of marker M15

M15 Y

Y-coordinate of marker M15

M15 Z

Z-coordinate of marker M15

M16 X

X-coordinate of marker M16

M16 Y

Y-coordinate of marker M16

M16 Z

Z-coordinate of marker M16

M17 X

X-coordinate of marker M17

M17 Y

Y-coordinate of marker M17

M17 Z

Z-coordinate of marker M17

M18 X

X-coordinate of marker M18

M18 Y

Y-coordinate of marker M18

M18 Z

Z-coordinate of marker M18

M19 X

X-coordinate of marker M19

M19 Y

Y-coordinate of marker M19

M19 Z

Z-coordinate of marker M19

M20 X

X-coordinate of marker M20

M20 Y

Y-coordinate of marker M20

M20 Z

Z-coordinate of marker M20

M21 X

X-coordinate of marker M21

M21 Y

Y-coordinate of marker M21

M21 Z

Z-coordinate of marker M21

M22 X

X-coordinate of marker M22

M22 Y

Y-coordinate of marker M22

M22 Z

Z-coordinate of marker M22

M23 X

X-coordinate of marker M23

M23 Y

Y-coordinate of marker M23

M23 Z

Z-coordinate of marker M23

M24 X

X-coordinate of marker M24

M24 Y

Y-coordinate of marker M24

M24 Z

Z-coordinate of marker M24

M25 X

X-coordinate of marker M25

M25 Y

Y-coordinate of marker M25

M25 Z

Z-coordinate of marker M25

M26 X

X-coordinate of marker M26

M26 Y

Y-coordinate of marker M26

M26 Z

Z-coordinate of marker M26

M27 X

X-coordinate of marker M27

M27 Y

Y-coordinate of marker M27

M27 Z

Z-coordinate of marker M27

M28 X

X-coordinate of marker M28

M28 Y

Y-coordinate of marker M28

M28 Z

Z-coordinate of marker M28

M29 X

X-coordinate of marker M29

M29 Y

Y-coordinate of marker M29

M29 Z

Z-coordinate of marker M29

M30 X

X-coordinate of marker M30

M30 Y

Y-coordinate of marker M30

M30 Z

Z-coordinate of marker M30

Details

This dataset can be used to analyze chest expansion and calculate the volume of chest segments using convex hull methods. The markers are placed around the chest, and the data tracks the chest wall motion over time.

Source

Collected using motion capture technology (e.g., Vicon system) for chest expansion studies.

Examples

data(sample_data)
head(sample_data)