{"id":34061435,"url":"https://github.com/pranavkokati/grainstat","last_synced_at":"2026-04-08T15:33:27.117Z","repository":{"id":305047591,"uuid":"1021743818","full_name":"pranavkokati/grainstat","owner":"pranavkokati","description":"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.","archived":false,"fork":false,"pushed_at":"2025-09-13T23:00:34.000Z","size":219,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-16T02:19:16.062Z","etag":null,"topics":["grain","materials","materials-science","microstructure","packages","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/grainstat/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pranavkokati.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-17T22:03:44.000Z","updated_at":"2025-12-09T06:32:22.000Z","dependencies_parsed_at":"2025-09-14T00:17:21.318Z","dependency_job_id":"44dcdda1-9e92-4db5-bd9e-a6ff6048407f","html_url":"https://github.com/pranavkokati/grainstat","commit_stats":null,"previous_names":["pranavkokati/grainstat"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/pranavkokati/grainstat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pranavkokati%2Fgrainstat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pranavkokati%2Fgrainstat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pranavkokati%2Fgrainstat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pranavkokati%2Fgrainstat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pranavkokati","download_url":"https://codeload.github.com/pranavkokati/grainstat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pranavkokati%2Fgrainstat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31562688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grain","materials","materials-science","microstructure","packages","python"],"created_at":"2025-12-14T04:56:24.943Z","updated_at":"2026-04-08T15:33:27.109Z","avatar_url":"https://github.com/pranavkokati.png","language":"Python","readme":"# GrainStat\n\n**Professional grain size analysis for materials science**\n\nGrainStat 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.\n\n## Features\n\n### 🔬 **Image Processing \u0026 Segmentation**\n- Support for TIFF, PNG, JPEG, BMP, and multi-page TIFF files\n- Spatial calibration for converting pixel measurements to physical units\n- Advanced preprocessing filters (Gaussian smoothing, CLAHE contrast enhancement)\n- Multiple thresholding methods (Otsu, adaptive)\n- Watershed segmentation for separating touching grains\n- Morphological operations for noise reduction\n\n### 📊 **Comprehensive Grain Analysis**\n- **Basic properties**: Area, perimeter, centroid, bounding box\n- **Shape descriptors**: Eccentricity, solidity, aspect ratio, orientation\n- **Derived metrics**: Equivalent circular diameter (ECD), shape factor, compactness\n- **ASTM E112 grain size number** calculation\n- **Size classification**: Ultrafine, fine, medium, coarse, very coarse\n\n### 📈 **Statistical Analysis**\n- Complete distribution statistics (mean, median, std, percentiles)\n- Skewness and kurtosis analysis\n- Population-level metrics and size uniformity\n- Spatial distribution analysis\n- Distribution fitting (normal, lognormal, gamma, Weibull)\n\n### 🎨 **Visualization Suite**\n- Size distribution histograms\n- Cumulative distribution plots\n- Grain overlay visualization with boundaries and labels\n- Shape analysis scatter plots\n- Multi-panel summary figures\n- Interactive grain viewer with click-to-inspect functionality\n\n### 📄 **Export \u0026 Reporting**\n- CSV/Excel export for grain data\n- JSON export for complete analysis results\n- Professional HTML/Markdown/PDF reports\n- Batch processing summaries\n- Grain boundary coordinate export\n\n### 🔧 **Advanced Features**\n- **Plugin system** for custom feature calculations\n- **Batch processing** with parallel execution\n- **Command-line interface** for automated workflows\n- **Interactive viewer** for detailed grain inspection\n- **Condition comparison** for experimental analysis\n\n## Installation\n\n### Quick Installation\n```bash\n# Clone the repository\ngit clone https://github.com/pranavkokati/grainstat.git\ncd grainstat\n\n# Install in editable mode (recommended for development)\npip install -e .\n\n# Or install normally\npip install .\n```\n\n### Alternative Installation Methods\n\n#### Method 1: From PyPI (when available)\n```bash\npip install grainstat\n```\n\n#### Method 2: With all optional dependencies\n```bash\npip install -e .[all]\n```\n\n#### Method 3: In a virtual environment (recommended)\n```bash\n# Create and activate virtual environment\npython -m venv grainstat_env\nsource grainstat_env/bin/activate  # On macOS/Linux\n# grainstat_env\\Scripts\\activate    # On Windows\n\n# Install grainstat\npip install -e .\n```\n\n### Troubleshooting Installation Issues\n\nIf you encounter `ModuleNotFoundError: No module named 'grainstat.core'`, try:\n\n```bash\n# Uninstall and reinstall\npip uninstall grainstat\npip install -e .\n\n# Verify installation\npython -c \"import grainstat; from grainstat.core import ImageLoader; print('✓ Installation successful')\"\n```\n\n### Requirements\n- Python 3.8+\n- NumPy, SciPy, scikit-image\n- Matplotlib, Pandas, Pillow\n- Seaborn (for enhanced plotting)\n\n## Quick Start\n\n### Basic Analysis\n\n```python\nfrom grainstat import GrainAnalyzer\n\n# Initialize analyzer\nanalyzer = GrainAnalyzer()\n\n# Analyze a microstructure image\nresults = analyzer.analyze(\n    image_path=\"microstructure.tif\",\n    scale=0.5,  # micrometers per pixel\n    min_area=50  # minimum grain area in pixels\n)\n\n# Export results\nanalyzer.export_csv(\"grain_data.csv\")\nanalyzer.generate_report(\"analysis_report.html\")\n\n# Generate plots\nanalyzer.plot_histogram(save_path=\"size_distribution.png\")\nanalyzer.plot_overlay(save_path=\"grain_overlay.png\")\n```\n\n### Command Line Usage\n\n```bash\n# Single image analysis\ngrainstat analyze image.tif --scale 0.2 --export-csv results.csv --report report.html\n\n# Batch processing\ngrainstat batch input_folder/ output_folder/ --scale 0.2 --workers 4\n\n# Interactive viewer\ngrainstat interactive image.tif --scale 0.2\n\n# Compare different conditions\ngrainstat compare --conditions condition1:path1 condition2:path2 output_dir/\n```\n\n### Batch Processing\n\n```python\nfrom grainstat.processing.batch import BatchProcessor\n\nprocessor = BatchProcessor(n_workers=4)\n\nresults = processor.process_directory(\n    input_dir=\"sample_images/\",\n    output_dir=\"batch_results/\",\n    scale=0.5,\n    pattern=\"*.tif\"\n)\n```\n\n### Custom Features with Plugins\n\n```python\nfrom grainstat import feature\n\n@feature\ndef custom_roundness(region):\n    \"\"\"Calculate custom roundness metric\"\"\"\n    area = region.area\n    perimeter = region.perimeter\n    return (4 * 3.14159 * area) / (perimeter ** 2)\n\n@feature(name=\"grain_complexity\")\ndef calculate_complexity(region):\n    \"\"\"Multi-parameter complexity measure\"\"\"\n    return {\n        'shape_complexity': region.eccentricity * (2 - region.solidity),\n        'size_factor': region.area / region.convex_area\n    }\n```\n\n## Analysis Workflow\n\n1. **Image Loading**: Automatic format detection and conversion to grayscale\n2. **Preprocessing**: Gaussian smoothing and contrast enhancement (CLAHE)\n3. **Segmentation**: Otsu or adaptive thresholding followed by watershed\n4. **Morphological Cleaning**: Opening, closing, and small object removal\n5. **Property Calculation**: Comprehensive geometric and shape analysis\n6. **Statistical Analysis**: Population statistics and distribution fitting\n7. **Visualization**: Multiple plot types for data exploration\n8. **Export**: Professional reports and data files\n\n## Key Formulas\n\n### Equivalent Circular Diameter (ECD)\n```\nECD = 2√(A/π)\n```\n\n### ASTM E112 Grain Size Number\n```\nG = -6.6438 × log₂(L) - 3.293\n```\nwhere L is the mean lineal intercept length in mm.\n\n### Shape Factor (Circularity)\n```\nφ = 4πA/P²\n```\n\n### Aspect Ratio\n```\nAR = a/b\n```\nwhere a and b are the major and minor axis lengths.\n\n## Output Examples\n\n### Statistical Summary\n```\nGRAIN ANALYSIS SUMMARY\n======================\nTotal grains detected: 1,247\nMean ECD: 12.3 μm\nMedian ECD: 10.8 μm\nASTM Grain Size Number: 8.2\n\nSize Class Distribution:\n  Fine: 423 grains (33.9%)\n  Medium: 681 grains (54.6%)\n  Coarse: 143 grains (11.5%)\n```\n\n### Exported Data\nThe CSV output includes all measured properties:\n- `grain_id`, `ecd_um`, `area_um2`, `perimeter_um`\n- `aspect_ratio`, `shape_factor`, `eccentricity`, `solidity`\n- `major_axis_um`, `minor_axis_um`, `orientation`\n- Custom plugin features\n\n## Applications\n\nGrainStat is designed for materials scientists, metallurgists, and researchers working with:\n\n- **Optical microscopy** of polished and etched samples\n- **SEM imaging** of microstructures\n- **Quality control** in materials processing\n- **Research** on grain growth, recrystallization, and phase transformations\n- **Standards compliance** (ASTM E112, ISO 643)\n\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Citation\n\nIf you use GrainStat in your research, please cite:\n\n```bibtex\n@software{grainstat2024,\n  title={GrainStat: Professional grain size analysis for materials science},\n  author={Pranav Kokati},\n  year={2024},\n  url={https://github.com/pranavkokati/grainstat}\n}\n```\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpranavkokati%2Fgrainstat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpranavkokati%2Fgrainstat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpranavkokati%2Fgrainstat/lists"}