FsMeshQC

FreeSurfer Mesh Quality Control Tool

Description

FsMeshQC is a specialized tool for analyzing and assessing the quality of cortical surface meshes generated by FreeSurfer. It computes various quality metrics for triangular mesh elements, identifies problematic areas, and generates comprehensive quality reports in multiple formats.

Features

• FreeSurfer Format Support: Reads standard FreeSurfer surface files (lh.white, rh.pial, etc.)
• Quality Metrics Calculation:
  • Shape quality
  • Triangle angles (min/max)
  • Edge lengths
  • Area calculations
  • Aspect ratio
  • Radius ratio
• Quality Assessment: Identifies problematic triangles using configurable thresholds
• Multiple Output Formats:
  • CSV format detailed face-by-face metrics
  • NPZ (NumPy compressed) format
  • JSON summary statistics
  • Optional Parquet format support
• Summary Statistics: Provides statistical overview of mesh quality

Installation

Using pip

pip install git+https://github.com/YCHuang0610/FsMeshQC.git

From source

git clone https://github.com/YCHuang0610/FsMeshQC.git
cd FsMeshQC
pip install -e .

Requirements

• Python 3.6+
• numpy
• nibabel
• pandas

Usage

Basic Usage

# Analyze a surface file with default settings
fsmeshqc /path/to/lh.white

# Specify custom output location
fsmeshqc /path/to/rh.pial -o ./results/my_quality_analysis

# Only display summary statistics without saving files
fsmeshqc /path/to/lh.white --summary-only

Advanced Options

# Adjust quality thresholds
fsmeshqc /path/to/lh.white --bad-sq-thresh 0.15 --bad-angle-thresh 8.0

# Control output formats
fsmeshqc /path/to/lh.white --no-csv --no-json --parquet

# Full command example with multiple options
fsmeshqc /path/to/lh.white -o ./results/lh_quality --no-npz --bad-sq-thresh 0.1

Command Line Arguments

Argument	Description
input_surf	Path to input FreeSurfer surface file
-o, --output	Output file prefix (default: input_filename_quality)
--csv/--no-csv	Enable/disable CSV output (default: enabled)
--npz/--no-npz	Enable/disable NPZ output (default: enabled)
--json/--no-json	Enable/disable JSON summary (default: enabled)
--parquet	Enable Parquet format output (default: disabled)
--bad-sq-thresh	Shape quality threshold (default: 0.2)
--bad-angle-thresh	Minimum angle threshold in degrees (default: 10.0)
--summary-only	Display summary only, don't save files

Output Files

For an input file lh.white with default output settings:

• lh.white_quality_faces.csv - Detailed face-by-face quality metrics
• lh.white_quality_faces.npz - NumPy compressed version of the same data
• lh.white_quality_summary.json - Statistical summary of quality metrics
• lh.white_quality_bad_faces.csv - List of low-quality triangles (if any)

Quality Metrics

• Shape Quality: Overall triangle shape quality metric (0-1, higher is better)
• Minimum Angle: Smallest angle in triangle (degrees)
• Maximum Angle: Largest angle in triangle (degrees)
• Edge Lengths: Three edge lengths of each triangle
• Area: Triangle area
• Radius Ratio: Inscribed/circumscribed circle radius ratio
• Aspect Proxy: Alternative aspect ratio metric

License

This project is licensed under the GNU License - see the LICENSE file for details.

Author

• ychunhuang - GitHub - ychunhuang@foxmail.com

Citation

If you use this tool in your research, please cite:

FsMeshQC: A FreeSurfer Mesh Quality Control Tool
Author: ychunhuang
URL: https://github.com/YCHuang0610/FsMeshQC