GrainStat

Professional grain size analysis for materials science

GrainStat is a comprehensive Python package for analyzing grain microstructures in materials science. It provides robust tools for image processing, grain segmentation, statistical analysis, and report generation that are essential for materials characterization.

Features

🔬 Image Processing & Segmentation

Support for TIFF, PNG, JPEG, BMP, and multi-page TIFF files
Spatial calibration for converting pixel measurements to physical units
Advanced preprocessing filters (Gaussian smoothing, CLAHE contrast enhancement)
Multiple thresholding methods (Otsu, adaptive)
Watershed segmentation for separating touching grains
Morphological operations for noise reduction

📊 Comprehensive Grain Analysis

Basic properties: Area, perimeter, centroid, bounding box
Shape descriptors: Eccentricity, solidity, aspect ratio, orientation
Derived metrics: Equivalent circular diameter (ECD), shape factor, compactness
ASTM E112 grain size number calculation
Size classification: Ultrafine, fine, medium, coarse, very coarse

📈 Statistical Analysis

Complete distribution statistics (mean, median, std, percentiles)
Skewness and kurtosis analysis
Population-level metrics and size uniformity
Spatial distribution analysis
Distribution fitting (normal, lognormal, gamma, Weibull)

🎨 Visualization Suite

Size distribution histograms
Cumulative distribution plots
Grain overlay visualization with boundaries and labels
Shape analysis scatter plots
Multi-panel summary figures
Interactive grain viewer with click-to-inspect functionality

📄 Export & Reporting

CSV/Excel export for grain data
JSON export for complete analysis results
Professional HTML/Markdown/PDF reports
Batch processing summaries
Grain boundary coordinate export

🔧 Advanced Features

Plugin system for custom feature calculations
Batch processing with parallel execution
Command-line interface for automated workflows
Interactive viewer for detailed grain inspection
Condition comparison for experimental analysis

Installation

Quick Installation

# Clone the repository
git clone https://github.com/pranavkokati/grainstat.git
cd grainstat

# Install in editable mode (recommended for development)
pip install -e .

# Or install normally
pip install .

Alternative Installation Methods

Method 1: From PyPI (when available)

pip install grainstat

Method 2: With all optional dependencies

pip install -e .[all]

Method 3: In a virtual environment (recommended)

# Create and activate virtual environment
python -m venv grainstat_env
source grainstat_env/bin/activate  # On macOS/Linux
# grainstat_env\Scripts\activate    # On Windows

# Install grainstat
pip install -e .

Troubleshooting Installation Issues

If you encounter ModuleNotFoundError: No module named 'grainstat.core', try:

# Uninstall and reinstall
pip uninstall grainstat
pip install -e .

# Verify installation
python -c "import grainstat; from grainstat.core import ImageLoader; print('✓ Installation successful')"

Requirements

Python 3.8+
NumPy, SciPy, scikit-image
Matplotlib, Pandas, Pillow
Seaborn (for enhanced plotting)

Quick Start

Basic Analysis

from grainstat import GrainAnalyzer

# Initialize analyzer
analyzer = GrainAnalyzer()

# Analyze a microstructure image
results = analyzer.analyze(
    image_path="microstructure.tif",
    scale=0.5,  # micrometers per pixel
    min_area=50  # minimum grain area in pixels
)

# Export results
analyzer.export_csv("grain_data.csv")
analyzer.generate_report("analysis_report.html")

# Generate plots
analyzer.plot_histogram(save_path="size_distribution.png")
analyzer.plot_overlay(save_path="grain_overlay.png")

Command Line Usage

# Single image analysis
grainstat analyze image.tif --scale 0.2 --export-csv results.csv --report report.html

# Batch processing
grainstat batch input_folder/ output_folder/ --scale 0.2 --workers 4

# Interactive viewer
grainstat interactive image.tif --scale 0.2

# Compare different conditions
grainstat compare --conditions condition1:path1 condition2:path2 output_dir/

Batch Processing

from grainstat.processing.batch import BatchProcessor

processor = BatchProcessor(n_workers=4)

results = processor.process_directory(
    input_dir="sample_images/",
    output_dir="batch_results/",
    scale=0.5,
    pattern="*.tif"
)

Custom Features with Plugins

from grainstat import feature

@feature
def custom_roundness(region):
    """Calculate custom roundness metric"""
    area = region.area
    perimeter = region.perimeter
    return (4 * 3.14159 * area) / (perimeter ** 2)

@feature(name="grain_complexity")
def calculate_complexity(region):
    """Multi-parameter complexity measure"""
    return {
        'shape_complexity': region.eccentricity * (2 - region.solidity),
        'size_factor': region.area / region.convex_area
    }

Analysis Workflow

Image Loading: Automatic format detection and conversion to grayscale
Preprocessing: Gaussian smoothing and contrast enhancement (CLAHE)
Segmentation: Otsu or adaptive thresholding followed by watershed
Morphological Cleaning: Opening, closing, and small object removal
Property Calculation: Comprehensive geometric and shape analysis
Statistical Analysis: Population statistics and distribution fitting
Visualization: Multiple plot types for data exploration
Export: Professional reports and data files

Key Formulas

Equivalent Circular Diameter (ECD)

ECD = 2√(A/π)

ASTM E112 Grain Size Number

G = -6.6438 × log₂(L) - 3.293

where L is the mean lineal intercept length in mm.

Shape Factor (Circularity)

φ = 4πA/P²

Aspect Ratio

AR = a/b

where a and b are the major and minor axis lengths.

Output Examples

Statistical Summary

GRAIN ANALYSIS SUMMARY
======================
Total grains detected: 1,247
Mean ECD: 12.3 μm
Median ECD: 10.8 μm
ASTM Grain Size Number: 8.2

Size Class Distribution:
  Fine: 423 grains (33.9%)
  Medium: 681 grains (54.6%)
  Coarse: 143 grains (11.5%)

Exported Data

The CSV output includes all measured properties:

grain_id, ecd_um, area_um2, perimeter_um
aspect_ratio, shape_factor, eccentricity, solidity
major_axis_um, minor_axis_um, orientation
Custom plugin features

Applications

GrainStat is designed for materials scientists, metallurgists, and researchers working with:

Optical microscopy of polished and etched samples
SEM imaging of microstructures
Quality control in materials processing
Research on grain growth, recrystallization, and phase transformations
Standards compliance (ASTM E112, ISO 643)

License

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

Citation

If you use GrainStat in your research, please cite:

@software{grainstat2024,
  title={GrainStat: Professional grain size analysis for materials science},
  author={Pranav Kokati},
  year={2024},
  url={https://github.com/pranavkokati/grainstat}
}

Grainstat

Install / Use

README