pyASDReader 1.2.0__py3-none-any.whl

pyasdreader-1.2.0.dist-info/METADATA

@@ -0,0 +1,497 @@
+Metadata-Version: 2.4
+Name: pyASDReader
+Version: 1.2.0
+Summary: A Python library for reading and parsing all versions of ASD binary spectral files
+Author-email: Kai Cao <caokai_cgs@163.com>
+Maintainer-email: Kai Cao <caokai_cgs@163.com>
+License: MIT License
+        
+        Copyright (c) 2025 Kai Cao
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/KaiTastic/pyASDReader
+Project-URL: Documentation, https://github.com/KaiTastic/pyASDReader#readme
+Project-URL: Repository, https://github.com/KaiTastic/pyASDReader
+Project-URL: Source, https://github.com/KaiTastic/pyASDReader
+Project-URL: Issues, https://github.com/KaiTastic/pyASDReader/issues
+Project-URL: Bug Reports, https://github.com/KaiTastic/pyASDReader/issues
+Project-URL: Changelog, https://github.com/KaiTastic/pyASDReader/blob/main/CHANGELOG.md
+Project-URL: PyPI, https://pypi.org/project/pyASDReader/
+Keywords: ASD,spectral files,spectroradiometer,remote sensing
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.10.0; extra == "dev"
+Requires-Dist: pytest-html>=3.0.0; extra == "dev"
+Requires-Dist: coverage>=5.0.0; extra == "dev"
+Requires-Dist: flake8>=3.8.0; extra == "dev"
+Requires-Dist: black>=21.0.0; extra == "dev"
+Requires-Dist: isort>=5.0.0; extra == "dev"
+Requires-Dist: build>=0.7.0; extra == "dev"
+Requires-Dist: twine>=3.0.0; extra == "dev"
+Requires-Dist: pre-commit>=2.15.0; extra == "dev"
+Requires-Dist: tox>=3.20.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=4.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
+Provides-Extra: all
+Requires-Dist: pytest>=6.0.0; extra == "all"
+Requires-Dist: pytest-cov>=2.10.0; extra == "all"
+Requires-Dist: pytest-html>=3.0.0; extra == "all"
+Requires-Dist: coverage>=5.0.0; extra == "all"
+Requires-Dist: flake8>=3.8.0; extra == "all"
+Requires-Dist: black>=21.0.0; extra == "all"
+Requires-Dist: isort>=5.0.0; extra == "all"
+Requires-Dist: build>=0.7.0; extra == "all"
+Requires-Dist: twine>=3.0.0; extra == "all"
+Requires-Dist: pre-commit>=2.15.0; extra == "all"
+Requires-Dist: tox>=3.20.0; extra == "all"
+Requires-Dist: sphinx>=4.0.0; extra == "all"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "all"
+Dynamic: license-file
+
+### pyASDReader - Python ASD Spectral File Reader
+
+[![PyPI version](https://img.shields.io/pypi/v/pyASDReader?style=flat-square)](https://pypi.org/project/pyASDReader/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyASDReader?style=flat-square)](https://pypi.org/project/pyASDReader/)
+[![License](https://img.shields.io/github/license/KaiTastic/pyASDReader?style=flat-square)](https://github.com/KaiTastic/pyASDReader/blob/main/LICENSE)
+[![Tests](https://img.shields.io/github/actions/workflow/status/KaiTastic/pyASDReader/test.yml?branch=main&label=tests&style=flat-square)](https://github.com/KaiTastic/pyASDReader/actions)
+[![Coverage](https://img.shields.io/codecov/c/github/KaiTastic/pyASDReader?style=flat-square)](https://codecov.io/gh/KaiTastic/pyASDReader)
+
+pyASDReader is a robust Python library designed to read and parse all versions (v1-v8) of ASD (Analytical Spectral Devices) binary spectral files. It provides seamless access to spectral data, metadata, and calibration information from various ASD instruments including FieldSpec, LabSpec, TerraSpec, and more.
+
+---
+
+## 🚀 Key Features
+
+- **Universal Compatibility**: Supports all ASD file versions (v1-v8) and instruments
+  - FieldSpec series (4 Hi-Res NG, 4 Hi-Res, 4 Standard-Res, 4 Wide-Res)
+  - LabSpec series (4 Bench, 4 Hi-Res, 4 Standard-Res)
+  - TerraSpec series (4 Hi-Res, 4 Standard-Res)
+  - HandHeld series (2 Pro, 2), AgriSpec, and more
+  
+- **Comprehensive Data Access**: Extract all spectral information
+  - Spectral data (reflectance, radiance, irradiance)
+  - Wavelength arrays and derivative calculations
+  - Complete metadata and instrument parameters
+  - Calibration data and reference measurements
+  
+- **Advanced Processing**: Built-in spectral analysis tools
+  - First and second derivative calculations
+  - Log(1/R) transformations
+  - Type-safe enum constants for file attributes
+  - Robust error handling and validation
+
+## Requirements
+
+- Python >=3.8
+- numpy >=1.20.0
+
+## Installation
+
+### Stable Release (Recommended)
+
+```bash
+pip install pyASDReader
+```
+
+### Development Installation
+
+For contributors and advanced users:
+
+```bash
+# Clone the repository
+git clone https://github.com/KaiTastic/pyASDReader.git
+cd pyASDReader
+
+# Install in editable mode with development dependencies
+pip install -e ".[dev]"
+
+# Install with all dependencies (dev + docs + testing)
+pip install -e ".[all]"
+```
+
+## Quick Start
+
+```python
+from pyASDReader import ASDFile
+
+# Method 1: Load file during initialization
+asd_file = ASDFile("path/to/your/spectrum.asd")
+
+# Method 2: Create instance first, then load
+asd_file = ASDFile()
+asd_file.read("path/to/your/spectrum.asd")
+
+# Access basic data
+wavelengths = asd_file.wavelengths    # Wavelength array
+reflectance = asd_file.reflectance    # Reflectance values
+metadata = asd_file.metadata          # File metadata
+```
+
+## Usage Examples
+
+### Basic Spectral Data Access
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+from pyASDReader import ASDFile
+
+# Load ASD file
+asd = ASDFile("sample_spectrum.asd")
+
+# Basic information
+print(f"File version: {asd.asdFileVersion}")
+print(f"Instrument: {asd.metadata.instrumentModel}")
+print(f"Number of channels: {len(asd.wavelengths)}")
+print(f"Spectral range: {asd.wavelengths[0]:.1f} - {asd.wavelengths[-1]:.1f} nm")
+
+# Plot spectrum
+plt.figure(figsize=(10, 6))
+plt.plot(asd.wavelengths, asd.reflectance)
+plt.xlabel('Wavelength (nm)')
+plt.ylabel('Reflectance')
+plt.title('ASD Spectrum')
+plt.grid(True)
+plt.show()
+```
+
+### Advanced Spectral Analysis
+
+```python
+# Access different spectral measurements
+reflectance = asd.reflectance                 # Raw reflectance
+abs_reflectance = asd.absoluteReflectance     # Absolute reflectance
+radiance = asd.radiance                       # Radiance data
+irradiance = asd.irradiance                   # Irradiance data
+
+# Derivative calculations
+refl_1st_deriv = asd.reflectance1stDeriv      # First derivative
+refl_2nd_deriv = asd.reflectance2ndDeriv      # Second derivative
+
+# Log(1/R) transformations
+log1r = asd.log1R                             # Log(1/R)
+log1r_1st_deriv = asd.log1R1stDeriv          # Log(1/R) first derivative
+log1r_2nd_deriv = asd.log1R2ndDeriv          # Log(1/R) second derivative
+```
+
+### Error Handling and Validation
+
+```python
+from pyASDReader import ASDFile
+import os
+
+def safe_read_asd(file_path):
+    """Safely read ASD file with error handling."""
+    try:
+        # Check if file exists
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"ASD file not found: {file_path}")
+        
+        # Load the file
+        asd = ASDFile(file_path)
+        
+        # Validate data
+        if asd.wavelengths is None or len(asd.wavelengths) == 0:
+            raise ValueError("Invalid or empty wavelength data")
+        
+        if asd.reflectance is None or len(asd.reflectance) == 0:
+            raise ValueError("Invalid or empty reflectance data")
+        
+        print(f"✓ Successfully loaded: {os.path.basename(file_path)}")
+        print(f"  Channels: {len(asd.wavelengths)}")
+        print(f"  Range: {asd.wavelengths[0]:.1f}-{asd.wavelengths[-1]:.1f} nm")
+        
+        return asd
+        
+    except Exception as e:
+        print(f"✗ Error loading {file_path}: {str(e)}")
+        return None
+
+# Usage
+asd_file = safe_read_asd("spectrum.asd")
+if asd_file is not None:
+    # Process the file
+    pass
+```
+
+### Batch Processing
+
+```python
+import glob
+from pathlib import Path
+
+def process_asd_directory(directory_path, output_format='csv'):
+    """Process all ASD files in a directory."""
+    asd_files = glob.glob(os.path.join(directory_path, "*.asd"))
+    
+    print(f"Found {len(asd_files)} ASD files")
+    
+    for file_path in asd_files:
+        try:
+            asd = ASDFile(file_path)
+            
+            # Extract filename without extension
+            base_name = Path(file_path).stem
+            
+            if output_format == 'csv':
+                # Save as CSV
+                output_path = f"{base_name}_spectrum.csv"
+                data = np.column_stack([asd.wavelengths, asd.reflectance])
+                np.savetxt(output_path, data, delimiter=',', 
+                          header='Wavelength(nm),Reflectance', comments='')
+                print(f"✓ Saved: {output_path}")
+                
+        except Exception as e:
+            print(f"✗ Error processing {file_path}: {str(e)}")
+
+# Usage
+process_asd_directory("./asd_data/", output_format='csv')
+```
+
+## API Reference
+
+### Core Classes
+
+#### `ASDFile`
+
+The main class for reading and parsing ASD files.
+
+**Constructor:**
+```python
+ASDFile(file_path: str = None)
+```
+
+**Key Properties:**
+| Property | Type | Description |
+|----------|------|-------------|
+| `wavelengths` | `numpy.ndarray` | Wavelength array (nm) |
+| `reflectance` | `numpy.ndarray` | Reflectance values |
+| `absoluteReflectance` | `numpy.ndarray` | Absolute reflectance |
+| `radiance` | `numpy.ndarray` | Radiance data |
+| `irradiance` | `numpy.ndarray` | Irradiance data |
+| `reflectance1stDeriv` | `numpy.ndarray` | First derivative of reflectance |
+| `reflectance2ndDeriv` | `numpy.ndarray` | Second derivative of reflectance |
+| `log1R` | `numpy.ndarray` | Log(1/R) transformation |
+| `log1R1stDeriv` | `numpy.ndarray` | First derivative of Log(1/R) |
+| `log1R2ndDeriv` | `numpy.ndarray` | Second derivative of Log(1/R) |
+| `metadata` | `object` | File metadata and instrument info |
+| `asdFileVersion` | `int` | ASD file format version |
+
+**Methods:**
+```python
+read(file_path: str) -> None
+    """Load and parse an ASD file."""
+```
+
+## Technical Documentation
+
+### ASD File Format Support
+
+pyASDReader supports all ASD file format versions and instrument models:
+
+#### Supported Instruments
+
+| **FieldSpec Series** | **LabSpec Series** | **TerraSpec Series** |
+|---------------------|-------------------|---------------------|
+| FieldSpec 4 Hi-Res NG | LabSpec 4 Bench | TerraSpec 4 Hi-Res |
+| FieldSpec 4 Hi-Res | LabSpec 4 Hi-Res | TerraSpec 4 Standard-Res |
+| FieldSpec 4 Standard-Res | LabSpec 4 Standard-Res | |
+| FieldSpec 4 Wide-Res | LabSpec range | |
+
+| **HandHeld Series** | **Other Models** |
+|-------------------|------------------|
+| HandHeld 2 Pro | AgriSpec |
+| HandHeld 2 | |
+
+#### File Structure Mapping
+
+| **ASD File Component** | **pyASDReader Property** |
+|----------------------|-------------------------|
+| Spectrum File Header | `asdFileVersion`, `metadata` |
+| Spectrum Data | `spectrumData` |
+| Reference File Header | `referenceFileHeader` |
+| Reference Data | `referenceData` |
+| Classifier Data | `classifierData` |
+| Dependent Variables | `dependants` |
+| Calibration Header | `calibrationHeader` |
+| Absolute/Base Calibration | `calibrationSeriesABS`, `calibrationSeriesBSE` |
+| Lamp Calibration Data | `calibrationSeriesLMP` |
+| Fiber Optic Data | `calibrationSeriesFO` |
+| Audit Log | `auditLog` |
+| Digital Signature | `signature` |
+
+### Validation and Testing
+
+pyASDReader has been extensively tested against **ASD ViewSpecPro 6.2.0** to ensure accuracy:
+
+#### ✅ **Validated Features**
+- Digital Number (DN) values
+- Reflectance calculations (raw, 1st derivative, 2nd derivative)
+- Absolute reflectance computations
+- Log(1/R) transformations (raw, 1st derivative, 2nd derivative)
+- Wavelength accuracy and calibration
+
+#### 🔄 **In Development**
+- Radiance calculations
+- Irradiance processing  
+- Parabolic jump correction algorithms
+
+### Upcoming Features
+
+#### Spectral Discontinuities Correction
+
+Advanced correction algorithms for spectral jumps at detector boundaries:
+
+- **Hueni Method**: Temperature-based correction using empirical formulas
+- **ASD Parabolic Method**: Parabolic interpolation for jump correction
+- Support for both automated and manual correction parameters
+
+#### Enhanced File Format Conversion
+
+Comprehensive export capabilities beyond the standard ASCII format:
+- Multiple output formats (CSV, JSON, HDF5, NetCDF)
+- Customizable data selection and filtering
+- Batch processing with parallel execution
+- Integration with popular spectral analysis libraries
+
+
+
+## Contributing
+
+### Development Setup
+
+1. **Fork and Clone**:
+   ```bash
+   git clone https://github.com/yourusername/pyASDReader.git
+   cd pyASDReader
+   ```
+
+2. **Create Development Environment**:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   pip install -e ".[dev]"
+   ```
+
+3. **Run Tests**:
+   ```bash
+   pytest tests/
+   python -m pytest --cov=src --cov-report=html
+   ```
+
+### Contribution Guidelines
+
+- **Bug Reports**: Use GitHub Issues with detailed reproduction steps
+- **Feature Requests**: Open an issue to discuss before implementing
+- **Code Style**: Follow PEP 8 and use provided pre-commit hooks
+- **Testing**: Add tests for new features and ensure all tests pass
+- **Documentation**: Update README and docstrings for any API changes
+
+### Development Workflow
+
+1. Create a feature branch: `git checkout -b feature/amazing-feature`
+2. Make your changes with appropriate tests
+3. Run the test suite: `pytest`
+4. Commit your changes: `git commit -m 'Add amazing feature'`
+5. Push to your fork: `git push origin feature/amazing-feature`
+6. Submit a Pull Request
+
+## � Support & Community
+
+### Getting Help
+
+- 📋 **GitHub Issues**: [Report bugs or request features](https://github.com/KaiTastic/pyASDReader/issues)
+- 📧 **Email**: `caokai_cgs@163.com` for direct support
+- 🔒 **Security**: Report vulnerabilities via our [Security Policy](SECURITY.md)
+
+### Community Guidelines
+
+- Be respectful and inclusive
+- Help others learn and grow
+- Share knowledge and experiences
+- Provide constructive feedback
+
+## Citation
+
+If you use pyASDReader in your research, please cite:
+
+```bibtex
+@software{cao2025pyasdreader,
+  author = {Cao, Kai},
+  title = {pyASDReader: A Python Library for ASD Spectral File Reading},
+  year = {2025},
+  url = {https://github.com/KaiTastic/pyASDReader},
+  version = {1.0.0}
+}
+```
+
+**Plain text citation**:
+> Cao, Kai. (2025). pyASDReader: A Python Library for ASD Spectral File Reading. https://github.com/KaiTastic/pyASDReader
+
+## 📖 References
+
+### Official Documentation
+- [ASD Inc. (2017). ASD File Format: Version 8 (Revision): 1-10](https://www.malvernpanalytical.com/en/learn/knowledge-center/user-manuals/asd-file-format-v8)
+- ASD Inc. Indico Version 7 File Format: 1-9
+- ASD Inc. (2008). ViewSpec Pro User Manual: 1-24  
+- ASD Inc. (2015). FieldSpec 4 User Manual: 1-10
+
+### Scientific References
+- [Hueni, A. and A. Bialek (2017). "Cause, Effect, and Correction of Field Spectroradiometer Interchannel Radiometric Steps." IEEE Journal of Selected Topics in Applied Earth Observations and Remote Sensing 10(4): 1542-1551](https://ieeexplore.ieee.org/document/7819458)
+
+## License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for complete details.
+
+### Built With
+
+- [NumPy](https://numpy.org/) - Numerical computing library
+- [Python](https://python.org/) - Programming language
+- [pytest](https://pytest.org/) - Testing framework
+
+---
+
+<div align="center">
+
+**[⬆ Back to Top](#pyasdreader)**
+
+Made with ❤️ for the spectroscopy community
+
+[![GitHub stars](https://img.shields.io/github/stars/KaiTastic/pyASDReader?style=social)](https://github.com/KaiTastic/pyASDReader/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/KaiTastic/pyASDReader?style=social)](https://github.com/KaiTastic/pyASDReader/network/members)
+
+</div>
+

pyasdreader-1.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pyASDReader/__init__.py,sha256=GJmksBkXsqptqJnT7PbspAEBUoU_lGvcwVd3fP8w__o,898
+pyASDReader/_version.py,sha256=Qoi-6vXsM2WM_PWcvneOkmz3YUHkQaYZutSOd6zFpmg,484
+pyASDReader/asd_file_reader.py,sha256=vPZP2VDRMqgj8kSTx0E8jN_OcsQhcA3Zy8QOeUkGkjc,49007
+pyASDReader/constant.py,sha256=Nb6KxsWOZun-SpMaackSHu_7WyImEWMzYbMZ0wsc5fI,4043
+pyASDReader/file_attributes.py,sha256=HFM2k_c2e7P_D9NdjYJcKrzm3jvy1R9H4cCM68WDVMA,4638
+pyASDReader/logger_setup.py,sha256=dq2pB3bsiSPnBSmY9vxpcq6O1HAe-aavRsjcxAXRJKU,1074
+pyasdreader-1.2.0.dist-info/licenses/LICENSE,sha256=oVMZWDdVKo3SjIabnhMqfhYrpC03xfcvwdwOn9jKObI,1085
+pyasdreader-1.2.0.dist-info/METADATA,sha256=OuSrJx3UDKFO0pWYJoOEwFu4HdBv4RFSFfS2ZBh6peM,17576
+pyasdreader-1.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyasdreader-1.2.0.dist-info/top_level.txt,sha256=ccFFeWZniznS8X6KVjgGSlfoMBac2ZHg5k56UKXJX4o,12
+pyasdreader-1.2.0.dist-info/RECORD,,

pyasdreader-1.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyasdreader-1.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kai Cao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyasdreader-1.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyASDReader