c2d-utils 0.0.1__tar.gz

c2d_utils-0.0.1/.gitignore

@@ -0,0 +1,48 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+pip-log.txt
+pip-delete-this-directory.txt
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+test-results.txt
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.vscode/
+.idea/
+*.swp
+*.swo

c2d_utils-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TU Wien
+
+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.

c2d_utils-0.0.1/Makefile

@@ -0,0 +1,23 @@
+.PHONY: init install test build upload clean
+
+init: clean
+	pip install -r requirements.txt
+
+create:
+	python3 -m venv .venv
+
+install:
+	pip install -e .
+
+test:
+	PYTHONPATH=src pytest tests/
+
+build: init
+	python3 -m build
+
+upload: build
+	python3 -m twine upload dist/*
+
+clean:
+	rm -rf dist
+	find . -type d -name '__pycache__' -exec rm -rf {} +

c2d_utils-0.0.1/PKG-INFO

@@ -0,0 +1,167 @@
+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")
+)
+```

c2d_utils-0.0.1/README.md

@@ -0,0 +1,151 @@
+# 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")
+)
+```

c2d_utils-0.0.1/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "c2d-utils"
+version = "0.0.1"
+description = "A shared infrastructure library for Pontus-X / C2D algorithms."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "TU Wien" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy",
+    "pandas",
+    "tables",
+    "matplotlib",
+    "xhtml2pdf",
+    "markdown"
+]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  "/.venv",
+  "/dist"
+]

c2d_utils-0.0.1/requirements.txt

@@ -0,0 +1 @@
+hatchling

c2d_utils-0.0.1/src/c2d_utils/__init__.py

@@ -0,0 +1,3 @@
+from c2d_utils.reader import get_file_data, ParsedHDF5FileContent, HDF5NodeInfo, save_extracted_images
+from c2d_utils.ctd_env import C2DContext
+from c2d_utils.reporting import ReportGenerator, export_html_to_pdf

c2d_utils-0.0.1/src/c2d_utils/ctd_env.py

@@ -0,0 +1,144 @@
+import os
+import sys
+import json
+import logging
+from pathlib import Path
+from typing import Dict, Any, List
+
+logger = logging.getLogger("c2d_utils.ctd_env")
+
+class C2DContext:
+    """Manages the Ocean Compute-to-Data (C2D) environment, directory structures,
+    and custom consumer parameters payload resolving.
+    """
+    def __init__(self, args=None, sample: str = None, out: str = None, 
+                 window: int = None, step: int = None, draft: int = None,
+                 compliance_only: bool = False):
+        
+        # Extract from args if provided, supporting both window and window_size variants
+        args_sample = getattr(args, "sample", None) if args else None
+        args_out = getattr(args, "out", None) if args else None
+        args_window = getattr(args, "window_size", None) if args else None
+        if args_window is None and args:
+            args_window = getattr(args, "window", None)
+        args_step = getattr(args, "step_size", None) if args else None
+        if args_step is None and args:
+            args_step = getattr(args, "step", None)
+        args_draft = getattr(args, "draft_size", None) if args else None
+        if args_draft is None and args:
+            args_draft = getattr(args, "draft", None)
+        args_compliance_only = getattr(args, "compliance_only", False) if args else False
+        
+        # Resolve values (explicit constructor kwargs override args namespace fields)
+        sample = sample if sample is not None else args_sample
+        out = out if out is not None else (args_out if args_out is not None else "/data/outputs")
+        window = window if window is not None else args_window
+        step = step if step is not None else args_step
+        draft = draft if draft is not None else args_draft
+        compliance_only = compliance_only or args_compliance_only
+        
+        # 1. Resolve Input File / Directory (DIDS environment variable takes precedence)
+        if os.environ.get("DIDS"):
+            try:
+                import json
+                dids = json.loads(os.environ.get("DIDS"))
+                if dids:
+                    self.input_file = Path(f"/data/inputs/{dids[0]}/0")
+                else:
+                    self.input_file = Path(os.environ.get("INPUT_DIR", "/data/inputs"))
+            except Exception:
+                self.input_file = Path(os.environ.get("INPUT_DIR", "/data/inputs"))
+        elif sample:
+            self.input_file = Path(sample)
+        else:
+            self.input_file = Path(os.environ.get("INPUT_DIR", "/data/inputs"))
+            
+        # 2. Resolve Output Directory
+        self.output_dir = Path(out)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+            
+        # 3. Load Pontus-X / Ocean Custom Parameters (algoCustomData.json)
+        self.custom_params = {}
+        custom_data_dir = self.input_file if self.input_file.is_dir() else self.input_file.parent
+        custom_data_file = custom_data_dir / "algoCustomData.json"
+        
+        if custom_data_file.exists():
+            try:
+                with open(custom_data_file, "r") as f:
+                    self.custom_params = json.load(f)
+                logger.info(f"Loaded custom C2D parameters from {custom_data_file}")
+            except Exception as e:
+                logger.warning(f"Failed to load custom parameters from {custom_data_file}: {e}")
+
+        # 4. Resolve parameters with overrides and fallbacks using matching names
+        self.window = self._resolve_param("window", window, 10000)
+        self.step = self._resolve_param("step", step, 2000)
+        self.draft = self._resolve_param("draft", draft, 2000)
+        
+        # 5. Resolve compliance-only mode
+        self.compliance_only = (
+            compliance_only or 
+            os.environ.get("COMPLIANCE_ONLY", "").lower() in ("true", "1", "yes")
+        )
+        self.log_params()
+
+    def log_params(self):
+        """Log the resolved C2D context parameters."""
+        logger.info("=================================================")
+        logger.info(f"Resolved Input File:  {self.input_file}")
+        logger.info(f"Resolved Output Dir:  {self.output_dir}")
+        logger.info(f"Rolling Window Size:  {self.window}")
+        logger.info(f"Rolling Step Size:    {self.step}")
+        logger.info(f"Draft Sample Limit:   {self.draft}")
+        logger.info(f"Compliance Only Mode: {self.compliance_only}")
+        logger.info("=================================================")
+        
+    def _resolve_param(self, name: str, override: int, default: int) -> int:
+        if override is not None:
+            return override
+        val = self.custom_params.get(name, os.environ.get(name.upper(), default))
+        try:
+            return int(val)
+        except (ValueError, TypeError):
+            logger.warning(f"Could not convert parameter {name}='{val}' to integer. Using default {default}")
+            return default
+
+    @property
+    def hdf5_files(self) -> List[Path]:
+        """Discovers and filters valid HDF5 files based on their magic bytes."""
+        if self.input_file.is_file():
+            return [self.input_file] if self._is_hdf5_file(self.input_file) else []
+        
+        if not self.input_file.exists():
+            return []
+            
+        candidates = []
+        for p in self.input_file.rglob("*"):
+            if p.is_file() and self._is_hdf5_file(p):
+                candidates.append(p)
+        return sorted(candidates)
+
+    def _is_hdf5_file(self, filepath: Path) -> bool:
+        """Check if file has HDF5 magic number (\x89HDF\r\n\x1a\n)."""
+        try:
+            if not filepath.is_file():
+                return False
+            with open(filepath, "rb") as f:
+                header = f.read(8)
+                return header == b"\x89HDF\r\n\x1a\n"
+        except Exception:
+            return False
+
+    @staticmethod
+    def setup_logging(log_level: str = "INFO"):
+        """Setup logger formatting."""
+        numeric_level = getattr(logging, log_level.upper(), None)
+        if not isinstance(numeric_level, int):
+            numeric_level = logging.INFO
+            
+        logging.basicConfig(
+            level=numeric_level,
+            format="%(asctime)s  %(levelname)-8s %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+            force=True
+        )

c2d_utils-0.0.1/src/c2d_utils/reader.py

@@ -0,0 +1,128 @@
+import logging
+import json
+import base64
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Any
+import pandas as pd
+
+logger = logging.getLogger("c2d_utils.reader")
+
+@dataclass
+class HDF5NodeInfo:
+    name: str
+    path: str
+    type: str
+    attributes: Dict[str, Any]
+
+@dataclass
+class ParsedHDF5FileContent:
+    acceleration_df: pd.DataFrame
+    sensor_df: pd.DataFrame
+    acceleration_meta: HDF5NodeInfo
+    pictures: Dict[str, List[str]]
+
+class MetadataPrefix:
+    PRE = "pre_metadata"
+    POST = "post_metadata"
+
+def get_node_names(hdf5_file_handle) -> List[str]:
+    """Return the path names of all root-level nodes."""
+    return [node._v_pathname for node in hdf5_file_handle.list_nodes("/")]
+
+def get_picture_node_names(hdf5_file_handle) -> List[str]:
+    """Return names of nodes that contain base64 picture data."""
+    return [name for name in get_node_names(hdf5_file_handle) if "pictures" in name]
+
+def parse_json_if_possible(val):
+    """Decode JSON from a string or bytes value, or return the value unchanged."""
+    if isinstance(val, (bytes, bytearray)):
+        try:
+            text = val.decode("utf-8")
+        except UnicodeDecodeError:
+            return val
+    elif isinstance(val, str):
+        text = val
+    else:
+        return val
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return val
+
+def node_to_dict(node) -> HDF5NodeInfo:
+    """Convert an HDF5 node's attribute store into a serialisable dataclass."""
+    info = HDF5NodeInfo(name=node._v_name, path=node._v_pathname,
+                        type=node.__class__.__name__, attributes={})
+    for key in node._v_attrs._f_list(attrset="all"):
+        raw = node._v_attrs[key]
+        if hasattr(raw, "tolist"):
+            pyval = raw.tolist()
+        elif hasattr(raw, "item"):
+            pyval = raw.item()
+        else:
+            pyval = raw
+        info.attributes[key] = parse_json_if_possible(pyval)
+    return info
+
+def get_file_data(file_path: Path) -> ParsedHDF5FileContent:
+    """Read and parse the structured data from an HDF5 measurement file."""
+    import tables
+    from tables import NoSuchNodeError
+    logger.info(f"Opening and parsing HDF5 file: {file_path.name}")
+
+    with tables.open_file(str(file_path), mode="r") as file_handle:
+        picture_node_names = get_picture_node_names(file_handle)
+        pictures: Dict[str, List[str]] = {}
+        for node_name in picture_node_names:
+            node = file_handle.get_node(node_name)
+            assert isinstance(node, tables.Array)
+            pictures[node_name.removeprefix("/")] = [
+                img.decode("utf-8") for img in node.read().tolist()
+            ]
+
+        try:
+            accel_node = file_handle.get_node("/acceleration")
+            assert isinstance(accel_node, tables.Table)
+            acceleration_df = pd.DataFrame.from_records(accel_node.read())
+            acceleration_meta = node_to_dict(accel_node)
+        except NoSuchNodeError:
+            logger.warning("No /acceleration table found in HDF5 file.")
+            acceleration_df = pd.DataFrame()
+            acceleration_meta = HDF5NodeInfo(name="acceleration", path="/acceleration", type="Table", attributes={})
+
+        try:
+            sensor_node = file_handle.get_node("/sensors")
+            assert isinstance(sensor_node, tables.Table)
+            sensor_df = pd.DataFrame.from_records(sensor_node.read())
+        except NoSuchNodeError:
+            logger.warning("No /sensors table found in HDF5 file.")
+            sensor_df = pd.DataFrame()
+
+    return ParsedHDF5FileContent(
+        acceleration_df=acceleration_df,
+        sensor_df=sensor_df,
+        acceleration_meta=acceleration_meta,
+        pictures=pictures,
+    )
+
+def save_extracted_images(pictures: Dict[str, List[str]], images_dir: Path):
+    """Decode and save base64 image strings as PNG / JPEG files."""
+    if not pictures:
+        logger.info("No pictures found to extract.")
+        return
+
+    logger.info(f"Extracting {len(pictures)} categories of images to {images_dir}")
+    for category, image_list in pictures.items():
+        category_dir = images_dir / category
+        category_dir.mkdir(parents=True, exist_ok=True)
+        for idx, img_data in enumerate(image_list):
+            try:
+                if "," in img_data:
+                    header, data = img_data.split(",", 1)
+                    ext = "jpg" if "jpeg" in header else "png"
+                else:
+                    data, ext = img_data, "png"
+                (category_dir / f"{idx}.{ext}").write_bytes(base64.b64decode(data))
+            except Exception as e:
+                logger.error(f"Failed to save image {category}/{idx}: {e}")

c2d_utils-0.0.1/src/c2d_utils/reporting.py

@@ -0,0 +1,288 @@
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+import logging
+from pathlib import Path
+from typing import List, Dict, Any
+
+logger = logging.getLogger("c2d_utils.reporting")
+
+class ReportGenerator:
+    """Common reporting class to ensure consistent styling and formatting across all PDF/HTML reports."""
+    
+    @staticmethod
+    def get_common_css() -> str:
+        """Returns the common CSS stylesheet used across all reports."""
+        return """
+            @page {
+                size: A4;
+                margin: 1.8cm;
+            }
+            body {
+                font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
+                font-size: 9.5px;
+                color: #334155;
+                line-height: 1.6;
+            }
+            h1 {
+                color: #0f172a;
+                font-size: 22pt;
+                font-weight: 700;
+                margin-top: 0px;
+                margin-bottom: 8px;
+                border-bottom: 2px solid #3b82f6;
+                padding-bottom: 6px;
+            }
+            h2 {
+                color: #1e293b;
+                font-size: 13pt;
+                font-weight: 600;
+                margin-top: 18px;
+                margin-bottom: 8px;
+                border-bottom: 1px solid #e2e8f0;
+                padding-bottom: 4px;
+            }
+            h3, h4 {
+                color: #2563eb;
+                font-size: 10.5pt;
+                font-weight: 600;
+                margin-top: 14px;
+                margin-bottom: 4px;
+            }
+            table {
+                width: 100%;
+                border-collapse: collapse;
+                margin-top: 10px;
+                margin-bottom: 12px;
+                font-size: 8px;
+            }
+            th {
+                background-color: #f1f5f9;
+                color: #1e293b;
+                font-weight: 600;
+                text-align: left;
+                padding: 5px 7px;
+                border: 1px solid #cbd5e1;
+            }
+            td {
+                border: 1px solid #cbd5e1;
+                padding: 4px 7px;
+                color: #334155;
+            }
+            tr:nth-child(even) {
+                background-color: #f8fafc;
+            }
+            .note {
+                background-color: #f8fafc;
+                border-left: 4px solid #3b82f6;
+                padding: 10px;
+                margin-bottom: 12px;
+                font-size: 9px;
+                color: #475569;
+            }
+            pre {
+                background: #f1f5f9;
+                padding: 8px;
+                font-size: 8px;
+                border-left: 3px solid #3b82f6;
+                margin-top: 10px;
+                margin-bottom: 10px;
+                color: #334155;
+            }
+            img {
+                display: block;
+                margin-left: auto;
+                margin-right: auto;
+                margin-top: 10px;
+                margin-bottom: 10px;
+            }
+            img.graph {
+                width: 520px;
+            }
+            img.snapshot-img {
+                width: 250px;
+            }
+            .page-break {
+                page-break-before: always;
+            }
+            .chart {
+                text-align: center;
+                margin: 15px 0;
+            }
+            .chart h3 {
+                margin-bottom: 5px;
+            }
+            .chart img {
+                width: 350px;
+            }
+            ul, ol {
+                margin-top: 5px;
+                margin-bottom: 10px;
+                padding-left: 20px;
+            }
+            li {
+                margin-bottom: 3px;
+            }
+        """
+
+    @classmethod
+    def build_html_document(cls, body_content: str, title: str = "Report") -> str:
+        """Wraps body content in a styled HTML document template."""
+        return f"""<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>{title}</title>
+    <style>
+        {cls.get_common_css()}
+    </style>
+</head>
+<body>
+    {body_content}
+</body>
+</html>"""
+
+    @staticmethod
+    def format_meta_val(v) -> str:
+        """Recursively formats metadata dictionary objects to readable strings."""
+        if isinstance(v, dict):
+            if "value" in v and "unit" in v:
+                return f"{v['value']} {v['unit']}"
+            return ", ".join(f"{k}: {ReportGenerator.format_meta_val(val)}" for k, val in v.items())
+        return str(v)
+
+    @staticmethod
+    def build_params_table(params: Dict[str, Any], keys_list: List[str], title_header: str) -> str:
+        """Build a 4-column HTML table from a list of keys, side-by-side (Attributes and Values)."""
+        rows = []
+        for k in sorted(keys_list):
+            if k in params:
+                key_name = k.replace('_', ' ').title()
+                if k.startswith("tool_r_at_"):
+                    pos = k.split("_")[-1]
+                    key_name = f"Tool Radius at {pos}mm"
+                rows.append((key_name, ReportGenerator.format_meta_val(params[k])))
+        
+        if not rows:
+            return ""
+            
+        n = len(rows)
+        half = (n + 1) // 2
+        left_half = rows[:half]
+        right_half = rows[half:]
+        
+        while len(right_half) < len(left_half):
+            right_half.append(("", ""))
+            
+        # Build HTML table with fixed widths to prevent right overflow
+        html = f"<h4>{title_header}</h4>\n"
+        html += '<table style="width: 100%; table-layout: fixed; border-collapse: collapse; margin-top: 10px; margin-bottom: 15px;">\n'
+        html += '  <thead>\n'
+        html += '    <tr>\n'
+        html += '      <th style="width: 25%; background-color: #006699; color: white; font-weight: bold; padding: 4px 6px; border: 1px solid #D0D0D0;">Attribute</th>\n'
+        html += '      <th style="width: 25%; background-color: #006699; color: white; font-weight: bold; padding: 4px 6px; border: 1px solid #D0D0D0;">Value</th>\n'
+        html += '      <th style="width: 25%; background-color: #006699; color: white; font-weight: bold; padding: 4px 6px; border: 1px solid #D0D0D0;">Attribute</th>\n'
+        html += '      <th style="width: 25%; background-color: #006699; color: white; font-weight: bold; padding: 4px 6px; border: 1px solid #D0D0D0;">Value</th>\n'
+        html += '    </tr>\n'
+        html += '  </thead>\n'
+        html += '  <tbody>\n'
+        for left, right in zip(left_half, right_half):
+            html += '    <tr>\n'
+            html += f'      <td style="width: 25%; padding: 4px 6px; border: 1px solid #D0D0D0; word-wrap: break-word;">{left[0]}</td>\n'
+            html += f'      <td style="width: 25%; padding: 4px 6px; border: 1px solid #D0D0D0; word-wrap: break-word;">{left[1]}</td>\n'
+            html += f'      <td style="width: 25%; padding: 4px 6px; border: 1px solid #D0D0D0; word-wrap: break-word;">{right[0]}</td>\n'
+            html += f'      <td style="width: 25%; padding: 4px 6px; border: 1px solid #D0D0D0; word-wrap: break-word;">{right[1]}</td>\n'
+            html += '    </tr>\n'
+        html += '  </tbody>\n'
+        html += '</table>\n'
+        return html
+
+    @classmethod
+    def render_markdown_to_pdf(cls, markdown_text: str, output_pdf_path: Path, base_dir: Path) -> bool:
+        """Converts Markdown content to a styled PDF using xhtml2pdf."""
+        try:
+            import markdown as md_lib
+            from xhtml2pdf import pisa
+            
+            # Convert markdown to html body
+            html_body = md_lib.markdown(markdown_text, extensions=["tables"])
+            html_document = cls.build_html_document(html_body, title="Report")
+            
+            def link_callback(uri, rel):
+                if uri.startswith("http://") or uri.startswith("https://"):
+                    return uri
+                resolved_path = base_dir / uri.lstrip("/")
+                if resolved_path.exists():
+                    return str(resolved_path)
+                cwd_path = Path.cwd() / uri.lstrip("/")
+                if cwd_path.exists():
+                    return str(cwd_path)
+                return uri
+
+            with open(output_pdf_path, "wb") as pdf_file:
+                pisa_status = pisa.CreatePDF(html_document, dest=pdf_file, link_callback=link_callback)
+            return not pisa_status.err
+        except Exception as e:
+            logger.error(f"Markdown PDF export failed: {e}")
+            return False
+
+def export_html_to_pdf(html_content: str, output_path: str) -> bool:
+    """Compile an HTML string into a PDF file using xhtml2pdf."""
+    try:
+        from xhtml2pdf import pisa
+        with open(output_path, "wb") as f_pdf:
+            pisa_status = pisa.CreatePDF(html_content, dest=f_pdf)
+        if pisa_status.err:
+            logger.error(f"xhtml2pdf error during rendering to {output_path}")
+            return False
+        return True
+    except Exception as e:
+        logger.error(f"Failed to generate PDF at {output_path}: {e}")
+        return False
+
+def plot_feature_importances(importances: np.ndarray, features: list, output_path: str):
+    """Plot feature importances as a horizontal bar chart."""
+    plt.figure(figsize=(8, 4.5))
+    sorted_idx = np.argsort(importances)
+    plt.barh(np.array(features)[sorted_idx], importances[sorted_idx], color="#1a73e8", edgecolor="none")
+    plt.xlabel("Mean Relative Importance")
+    plt.title("Feature Importance Ranking (Random Forest Regressor)")
+    plt.tight_layout()
+    plt.savefig(output_path, dpi=150)
+    plt.close()
+
+def plot_model_comparison(targets: list, rf_maes: list, ridge_maes: list, output_path: str):
+    """Plot Mean Absolute Error (MAE) comparisons between Ridge and Random Forest."""
+    plt.figure(figsize=(8, 4.5))
+    x_indices = np.arange(len(targets))
+    width = 0.35
+    plt.bar(x_indices - width/2, np.array(rf_maes) * 1000.0, width, label="Random Forest", color="#1a73e8")
+    plt.bar(x_indices + width/2, np.array(ridge_maes) * 1000.0, width, label="Ridge Regression", color="#dadce0")
+    plt.ylabel("Mean Absolute Error (μm)")
+    plt.xticks(x_indices, [f"{i}mm" for i in range(len(targets))])
+    plt.xlabel("Measurement Position from Spindle Tip")
+    plt.title("Prediction Error Comparison (MAE)")
+    plt.legend()
+    plt.tight_layout()
+    plt.savefig(output_path, dpi=150)
+    plt.close()
+
+def plot_correlation_heatmap(df_clean: pd.DataFrame, features: list, targets: list, output_path: str):
+    """Plot a Pearson correlation heatmap of features vs. targets."""
+    corr_matrix = df_clean[features + targets].corr().loc[features, targets]
+    plt.figure(figsize=(8, 5.5))
+    im = plt.imshow(corr_matrix, cmap="coolwarm", vmin=-1.0, vmax=1.0, aspect="auto")
+    plt.colorbar(im, label="Pearson Correlation Coeff.")
+    plt.yticks(np.arange(len(features)), features)
+    plt.xticks(np.arange(len(targets)), [f"{i}mm" for i in range(len(targets))])
+    plt.title("Feature-Target Correlation Matrix Heatmap")
+    
+    # Annotate correlation values
+    for ii in range(len(features)):
+        for jj in range(len(targets)):
+            val = corr_matrix.iloc[ii, jj]
+            plt.text(jj, ii, f"{val:.2f}", ha="center", va="center", color="white" if abs(val) > 0.5 else "black", fontsize=8)
+            
+    plt.tight_layout()
+    plt.savefig(output_path, dpi=150)
+    plt.close()