Package 'ChestVolume'

Adjust Marker Positions Towards Center

Description

Adjusts the positions of markers by moving them towards the average center position within each timeframe by a specified distance. This accounts for marker protrusion from the skin surface.

Usage

adj_position(data, distance = 1)

Arguments

data	A data frame where each row represents a marker at a specific timeframe, with columns 'Timeframe', 'Marker', 'X', 'Y', 'Z'.
distance	Numeric value indicating the distance to adjust towards the center (default is 1 cm).

Details

The function calculates the average center position of all markers within each timeframe and moves each marker towards the center by the specified distance along the line connecting the marker to the center.

Value

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

Examples

data("sample_data")
processed_data <- process_marker_data(head(sample_data))
adjusted_data <- adj_position(processed_data, distance = 1)
head(adjusted_data)

---

Calculate Segment Volumes Over Time

Description

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

Usage

calculate_volumes(data, segments)

Arguments

data	A data frame containing adjusted marker coordinates in centimeters, with columns 'Timeframe', 'Marker', 'X', 'Y', 'Z'.
segments	A list of character vectors, each containing marker names defining a segment.

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')
processed_data <- process_marker_data(head(sample_data))
adjusted_data <- adj_position(processed_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

volume_data	A data frame with volume measurements, one column per segment, and a "frame" column for time.
segment_names	Column that contain name of segment to plot
title	Optional plot title.

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

data	A data frame containing adjusted marker coordinates, with columns 'Timeframe', 'Marker', 'X', 'Y', 'Z'. Coordinates should be in consistent units (e.g., centimeters).
segments	A named list where each element is a character vector of marker names defining a segment.
selected_segment	A character string specifying the name of the segment to highlight.
timeframe	A numeric value indicating the timeframe to plot. If NULL, the first timeframe is used.
point_size	Numeric value specifying the size of the markers in the plot (default is 5).
highlight_color	Color to use for the highlighted segment markers and mesh (default is 'red').
marker_color	Color to use for the non-highlighted markers (default is 'blue').

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

---

Process and Sort Marker Data for All Time Frames

Description

Processes 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

process_marker_data(data, convert_to_cm = TRUE)

Arguments

data	A data frame containing marker coordinate data for all time frames. Columns should be named in the format 'MXX X', 'MXX Y', 'MXX Z' where 'MXX' is the marker name.
convert_to_cm	Logical, if TRUE, divides X, Y, Z coordinates by 10 to convert to centimeters (from millimeters).

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

filepath

A string specifying the path to the Excel file containing segment definitions.

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)

---

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)

---

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

---