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:

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

# 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.

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:

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).

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")
)