Metadata-Version: 2.4
Name: xtvreader
Version: 1.1.0
Summary: Python module for reading TRACE XTV graphics files
Author-email: Josh Whitman <Josh.Whitman@nrc.gov>, Chris Murray <Christopher.Murray@nrc.gov>, Andrew Ireland <Andrew.Ireland@nrc.gov>, Chester Gingrich <Chester.Gingrich@nrc.gov>
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: py-xdrlib>=1.0
Dynamic: license-file

# xtvreader

Python application for reading TRACE XTV graphics files.

This is the Python 3.x version of the application. References in documentation or examples to `import xtvreader` work out of the box when the package is installed.

Originally written by Josh Whitman.

---

## Installation

We recommend installing `xtvreader` as a standard package.

### 1. From a Local Clone
To install the package in your active Python environment, navigate to the repository root and run:
```bash
pip install .
```

### 2. Editable/Development Mode
If you are developing or modifying the library, install it in editable mode:
```bash
pip install -e .
```

### 3. Directly from GitHub
You can install `xtvreader` directly from the repository using pip:
```bash
pip install git+https://github.com/NRC-Research/xtvReader.git
```

---

## Dependencies

The package requires `py-xdrlib>=1.0` as a dependency to ensure compatibility with Python 3.11+ and Python 3.13 (where `xdrlib` was removed from the standard library). This is handled automatically by pip during installation.

---

## Virtual Environment Setup

To keep your system Python clean, we encourage using a virtual environment:

```bash
# Create a virtual environment
python3 -m venv .venv

# Activate it
source .venv/bin/activate  # On macOS/Linux
# .venv\Scripts\activate  # On Windows

# Install the package locally
pip install -e .
```

---

## Usage

### In a Python Script
You can import `XtvFile` directly from the package:

```python
from xtvreader import XtvFile

# Open an XTV file
with open('path/to/file.xtv', 'rb') as f:
    xtv = XtvFile(f)
    
    # Retrieve a data channel value
    data = xtv.getTimeVector('alpn-1A02')
    print(data)
```

### Command Line Tools
Two utility scripts are provided at the root of the repository:
*   `xtv2csv.py`: Convert XTV graphics files to CSV format.
    ```bash
    python xtv2csv.py file.xtv -var alpn-1A02
    ```
*   `htstrTest.py`: Read and extract peak cladding temperature (PCT) data from heat structures.
    ```bash
    python htstrTest.py
    ```

---

## Original Module Details

`xtvreader` is a native Python module for retrieving values from a TRACE XTV file. It exposes the `XtvFile` class which reads header information and spawns component objects dynamically. The header information determines exactly which bytes must be read to extract a specific data point at any edit. If times or axial locations are requested between edits or mesh indices, values are interpolated linearly.

### Limitations
It does not contain any of the batch command helper functions that AptPlot and PyPost batch languages provide.
