Metadata-Version: 2.4
Name: c2d-utils
Version: 0.0.1
Summary: A shared infrastructure library for Pontus-X / C2D algorithms.
Author: TU Wien
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: markdown
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: tables
Requires-Dist: xhtml2pdf
Description-Content-Type: text/markdown

# C2D-Utils

A shared infrastructure and data-access SDK for Pontus-X / Compute-to-Data (C2D) manufacturing analytics and milling diagnostics algorithms.

## Features
* **C2D Environment Context**: Resolves Pontus-X DID input directories, handles consumer customization payloads, auto-creates output directories, and automates parameter logging.
* **HDF5 Parsing Engine**: Extracts high-frequency vibration streams, sensor calibration tables, and base64 camera blob nodes.
* **Universal PDF Reporting**: Renders Markdown/HTML documents to A4 PDFs with sleek slate-and-blue stylesheets and fixed-width 4-column parameters tables.

---

## Installation
To install the package locally in editable development mode:
```bash
pip install -e .
```

---

## Local Development Flow

When building and testing algorithms locally, you override the default Ocean C2D directories by passing manual arguments to your CLI script:

* **`--sample <path>`**: The path to a local HDF5 file or directory of datasets.
* **`--out <path>`**: The directory where outputs (plots, CSVs, and PDF reports) are saved. If the specified directory does not exist, `C2DContext` will automatically create it (including all parent paths) on instantiation.

### Execution Example
```bash
# Run single report on a local file and output to outputs/single_run
python run_single_report.py --sample test-data/cirp_twm_1.hdf5 --out outputs/single_run
```

---

## Usage Examples

### 1. Manual CLI Definition & C2D Context Resolution
Define your command line flags manually, and instantiate `C2DContext`. The library dynamically checks the `DIDS` environment array. If found, it targets the C2D mounted dataset `/data/inputs/{DID}/0`. Otherwise, it falls back to your local `--sample` input path.

```python
import argparse
import sys
import logging
from c2d_utils.ctd_env import C2DContext

logger = logging.getLogger("ocean_c2d.run_single_report")

def main():
    parser = argparse.ArgumentParser(description="HDF5 Process Analytics - Single Dataset Report Generator")
    parser.add_argument(
        '--log',
        default='INFO',
        help='Set the logging level. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL'
    )
    parser.add_argument(
        '--sample',
        default=None,
        help='Run sample file.'
    )
    parser.add_argument(
        '--out',
        default="/data/outputs",
        help='Output directory.'
    )
    parser.add_argument("--window_size", type=int, default=None, help="Window size for RMS")
    parser.add_argument("--step_size", type=int, default=None, help="Step size for RMS")
    parser.add_argument("--draft_size", type=int, default=None, help="Draft size for zoom")

    args, unknown = parser.parse_known_args()
    C2DContext.setup_logging(args.log)

    logger.info("=================================================")
    logger.info("***  HDF5 Single Dataset Analytics Tool       ***")
    logger.info("=================================================")

    # Initialize environment context:
    # 1. Resolves Pontus-X or local directories.
    # 2. Automatically runs `output_dir.mkdir(parents=True, exist_ok=True)`.
    # 3. Logs a clean parameters summary to the console.
    ctx = C2DContext(args)

    # Access resolved variables
    print(f"Loading files from: {ctx.input_file}")
    print(f"Writing results to: {ctx.output_dir}")
```

### 2. Reading HDF5 Sensor Streams & Camera Blobs
Parse the acceleration tables, raw calibration properties, and base64 inspection frames from an HDF5 database:

```python
from pathlib import Path
from c2d_utils.reader import get_file_data, save_extracted_images

# Parse HDF5 structure
content = get_file_data(Path("measurement.hdf5"))

# Access high-frequency vibration signals
acceleration_df = content.acceleration_df
x_signal = acceleration_df["x"].values
timestamps = acceleration_df["timestamp"].values

# Decode and write camera frame blobs to output folder
save_extracted_images(content.pictures, Path("output/images"))
```

### 3. Reporting Functions & PDF Compilation
The `c2d-utils` reporting module provides two core helper functions to compile professional, print-ready reports:

#### A. `ReportGenerator.build_params_table(data_dict, keys_to_include, table_title)`
Formats a raw dictionary into a structured, 4-column parameter table. The table is automatically split to fit within A4 boundaries (columns 1 & 2 show the first half, columns 3 & 4 show the second half with the same titles):
* `data_dict`: Raw data dictionary containing the parameters.
* `keys_to_include`: A list of strings/keys to select from `data_dict`.
* `table_title`: The display header for the table.

#### B. `ReportGenerator.render_markdown_to_pdf(markdown_text, output_pdf_path, base_dir)`
Compiles markdown syntax and embedded HTML tables/images into an A4 PDF document using a modern slate-and-blue design scheme:
* `markdown_text`: The string content in Markdown format.
* `output_pdf_path`: The `Path` where the final `.pdf` file will be saved.
* `base_dir`: The directory to resolve relative paths of referenced asset images (e.g. graphs, snapshots).

```python
from pathlib import Path
from c2d_utils.reporting import ReportGenerator

# 1. Build a 4-column parameter table
raw_params = {
    "Cutter Diameter": "10 mm",
    "Spindle Speed": "2546 RPM",
    "Tooth Count": "2",
    "Max Depth": "1.5 mm"
}
keys = ["Cutter Diameter", "Spindle Speed", "Tooth Count", "Max Depth"]
param_table_html = ReportGenerator.build_params_table(raw_params, keys, "Tool Specifications")

# 2. Construct Markdown report layout
report_markdown = f"""
# Process Diagnostics Report

{param_table_html}

## Vibration Profile
<img class="graph" src="vibration_analysis.png" />
"""

# 3. Render Markdown layout to PDF
success = ReportGenerator.render_markdown_to_pdf(
    markdown_text=report_markdown,
    output_pdf_path=Path("outputs/single_run/result.pdf"),
    base_dir=Path("outputs/single_run")
)
```
