tcv-screenshots 0.3.0__tar.gz

tcv_screenshots-0.3.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: tcv-screenshots
+Version: 0.3.0
+Summary: Headless screenshot generator for three-cad-viewer
+Author: Bernhard Walter
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: ocp_tessellate
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+
+# tcv-screenshots
+
+Headless screenshot generator for three-cad-viewer. Render 3D CAD models to PNG screenshots.
+
+## Supported Platforms
+
+- Linux (Intel, ARM)
+- Windows (Intel)
+- macOS (Intel, Apple Silicon)
+
+## Installation
+
+```bash
+pip install tcv-screenshots
+playwright install chromium
+```
+
+If you use build123d for creating 3D objects, `build123d` neeeds to be installed, similar for CadQuery.
+
+## Usage
+
+```bash
+# Single file (output to current directory)
+python -m tcv_screenshots -f example.py
+
+# Single file with output folder
+python -m tcv_screenshots -f example.py -o screenshots
+
+# Directory of examples (requires -o)
+python -m tcv_screenshots -d examples -o screenshots
+```
+
+**Options:**
+
+- `-f, --file FILE` - Single Python example file to process
+- `-d, --directory DIR` - Directory containing Python example files (requires -o)
+- `-o, --output-folder DIR` - Output directory for PNG screenshots
+- `--no-headless` - Show browser window (for debugging)
+- `--pause` - Pause before each screenshot (for debugging)
+- `--debug MODELS_DIR` - Save JSON model files to directory (for debugging)
+
+## Writing Examples
+
+Create a Python file with a `main()` function that uses `save_model` and returns `get_saved_models()`:
+
+```python
+from build123d import *
+
+model = Box(10, 20, 30)
+
+def main():
+    from tcv_screenshots import save_model, get_saved_models
+
+    save_model(model, "box", {"cadWidth": 800, "height": 600})
+    return get_saved_models()
+```
+
+### Multiple Models per Example
+
+For incremental examples that need screenshots at different stages:
+
+```python
+from build123d import *
+
+# Step 1: Create base box
+box = Box(10, 10, 10)
+
+# Step 2: Add fillet
+filleted = fillet(box.edges(), 1)
+
+# Step 3: Add hole
+final = filleted - Cylinder(2, 10)
+
+def main():
+    from tcv_screenshots import save_model, get_saved_models
+
+    config = {"cadWidth": 500, "height": 375}
+
+    save_model(box, "step1_box", config)
+    save_model(filleted, "step2_fillet", config)
+    save_model(final, "step3_hole", {**config, "render_edges": False})
+
+    return get_saved_models()
+```
+
+This generates `step1_box.png`, `step2_fillet.png`, and `step3_hole.png`.
+
+### Available Config Options
+
+See [VS Code CAD Viewer's show command](https://github.com/bernhard-42/vscode-ocp-cad-viewer/blob/main/docs/show.md)
+
+#### Examples
+
+**Display options:**
+
+- `cadWidth` - Viewport width (default: 1200)
+- `height` - Viewport height (default: 800)
+- `treeWidth` - Tree panel width (default: 0)
+- `theme` - 'light' or 'dark' (default: 'light')
+- `glass` - Glass mode (default: True)
+- `tools` - Show tools (default: False)
+
+**Render options:**
+
+- `ambientIntensity` - Ambient light intensity (default: 1.0)
+- `directIntensity` - Direct light intensity (default: 1.1)
+- `metalness` - Material metalness (default: 0.3)
+- `roughness` - Material roughness (default: 0.65)
+- `edgeColor` - Edge color as hex int (default: 0x707070)
+- `render_edges` - Show edges (default: True)
+- `render_faces` - Show faces (default: True)
+
+**Viewer options:**
+
+- `ortho` - Orthographic projection (default: True)
+- `control` - Control type (default: 'trackball')
+- `up` - Up axis: 'Z' or 'Y' (default: 'Z')
+- `tab` - Active tab: 'tree', 'clip', 'material'
+- `reset_camera` - Camera view: 'iso', 'front', 'rear', 'left', 'right', 'top', 'bottom'
+
+## CI/CD
+
+`tcv_screenshots` can be used in CI/CD workflows, an example can seen in [.github/workflows/screenshots.yml](.github/workflows/screenshots.yml)
+
+## Development
+
+Build the wheel:
+
+```bash
+pip install build
+python -m build
+```

tcv_screenshots-0.3.0/README.md

@@ -0,0 +1,132 @@
+# tcv-screenshots
+
+Headless screenshot generator for three-cad-viewer. Render 3D CAD models to PNG screenshots.
+
+## Supported Platforms
+
+- Linux (Intel, ARM)
+- Windows (Intel)
+- macOS (Intel, Apple Silicon)
+
+## Installation
+
+```bash
+pip install tcv-screenshots
+playwright install chromium
+```
+
+If you use build123d for creating 3D objects, `build123d` neeeds to be installed, similar for CadQuery.
+
+## Usage
+
+```bash
+# Single file (output to current directory)
+python -m tcv_screenshots -f example.py
+
+# Single file with output folder
+python -m tcv_screenshots -f example.py -o screenshots
+
+# Directory of examples (requires -o)
+python -m tcv_screenshots -d examples -o screenshots
+```
+
+**Options:**
+
+- `-f, --file FILE` - Single Python example file to process
+- `-d, --directory DIR` - Directory containing Python example files (requires -o)
+- `-o, --output-folder DIR` - Output directory for PNG screenshots
+- `--no-headless` - Show browser window (for debugging)
+- `--pause` - Pause before each screenshot (for debugging)
+- `--debug MODELS_DIR` - Save JSON model files to directory (for debugging)
+
+## Writing Examples
+
+Create a Python file with a `main()` function that uses `save_model` and returns `get_saved_models()`:
+
+```python
+from build123d import *
+
+model = Box(10, 20, 30)
+
+def main():
+    from tcv_screenshots import save_model, get_saved_models
+
+    save_model(model, "box", {"cadWidth": 800, "height": 600})
+    return get_saved_models()
+```
+
+### Multiple Models per Example
+
+For incremental examples that need screenshots at different stages:
+
+```python
+from build123d import *
+
+# Step 1: Create base box
+box = Box(10, 10, 10)
+
+# Step 2: Add fillet
+filleted = fillet(box.edges(), 1)
+
+# Step 3: Add hole
+final = filleted - Cylinder(2, 10)
+
+def main():
+    from tcv_screenshots import save_model, get_saved_models
+
+    config = {"cadWidth": 500, "height": 375}
+
+    save_model(box, "step1_box", config)
+    save_model(filleted, "step2_fillet", config)
+    save_model(final, "step3_hole", {**config, "render_edges": False})
+
+    return get_saved_models()
+```
+
+This generates `step1_box.png`, `step2_fillet.png`, and `step3_hole.png`.
+
+### Available Config Options
+
+See [VS Code CAD Viewer's show command](https://github.com/bernhard-42/vscode-ocp-cad-viewer/blob/main/docs/show.md)
+
+#### Examples
+
+**Display options:**
+
+- `cadWidth` - Viewport width (default: 1200)
+- `height` - Viewport height (default: 800)
+- `treeWidth` - Tree panel width (default: 0)
+- `theme` - 'light' or 'dark' (default: 'light')
+- `glass` - Glass mode (default: True)
+- `tools` - Show tools (default: False)
+
+**Render options:**
+
+- `ambientIntensity` - Ambient light intensity (default: 1.0)
+- `directIntensity` - Direct light intensity (default: 1.1)
+- `metalness` - Material metalness (default: 0.3)
+- `roughness` - Material roughness (default: 0.65)
+- `edgeColor` - Edge color as hex int (default: 0x707070)
+- `render_edges` - Show edges (default: True)
+- `render_faces` - Show faces (default: True)
+
+**Viewer options:**
+
+- `ortho` - Orthographic projection (default: True)
+- `control` - Control type (default: 'trackball')
+- `up` - Up axis: 'Z' or 'Y' (default: 'Z')
+- `tab` - Active tab: 'tree', 'clip', 'material'
+- `reset_camera` - Camera view: 'iso', 'front', 'rear', 'left', 'right', 'top', 'bottom'
+
+## CI/CD
+
+`tcv_screenshots` can be used in CI/CD workflows, an example can seen in [.github/workflows/screenshots.yml](.github/workflows/screenshots.yml)
+
+## Development
+
+Build the wheel:
+
+```bash
+pip install build
+python -m build
+```

tcv_screenshots-0.3.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tcv-screenshots"
+version = "0.3.0"
+description = "Headless screenshot generator for three-cad-viewer"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Bernhard Walter" }]
+dependencies = ["playwright>=1.40.0", "ocp_tessellate"]
+
+[project.optional-dependencies]
+dev = ["build"]
+
+[tool.setuptools.packages.find]
+include = ["tcv_screenshots*"]
+
+[tool.setuptools.package-data]
+tcv_screenshots = ["*.html", "*.js", "*.css"]

tcv_screenshots-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tcv_screenshots-0.3.0/tcv_screenshots/__init__.py

@@ -0,0 +1,40 @@
+"""Headless screenshot generator for three-cad-viewer."""
+
+__version__ = "0.1.0"
+
+# Model collector for incremental examples
+_saved_models = []
+
+
+def save_model(model, name: str, config: dict = None):
+    """
+    Save a model for later export.
+
+    Call this at different points in your example code to capture
+    incremental states. Then have main() return get_saved_models().
+
+    Args:
+        model: CAD object to render
+        name: Unique name for this snapshot (used in filename)
+        config: Optional config overrides
+    """
+    _saved_models.append((model, name, config or {}))
+
+
+def get_saved_models() -> list:
+    """
+    Get all saved models and clear the collector.
+
+    Returns:
+        List of (model, name, config) tuples
+    """
+    global _saved_models
+    models = _saved_models.copy()
+    _saved_models = []
+    return models
+
+
+def clear_saved_models():
+    """Clear the saved models collector."""
+    global _saved_models
+    _saved_models = []

tcv_screenshots-0.3.0/tcv_screenshots/__main__.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Entry point for python -m tcv_screenshots."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from .render import run
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="tcv_screenshots",
+        description="Generate screenshots from CAD examples using three-cad-viewer"
+    )
+
+    # Input source (mutually exclusive)
+    input_group = parser.add_mutually_exclusive_group(required=True)
+    input_group.add_argument(
+        "-f", "--file",
+        type=Path,
+        help="Single Python example file to process",
+    )
+    input_group.add_argument(
+        "-d", "--directory",
+        type=Path,
+        help="Directory containing Python example files (requires -o)",
+    )
+
+    parser.add_argument(
+        "-o", "--output-folder",
+        type=Path,
+        help="Output directory for PNG screenshots",
+    )
+    parser.add_argument(
+        "--no-headless",
+        action="store_true",
+        help="Run browser in visible mode (for debugging)",
+    )
+    parser.add_argument(
+        "--pause",
+        action="store_true",
+        help="Pause before each screenshot (for debugging)",
+    )
+    parser.add_argument(
+        "--debug",
+        type=Path,
+        metavar="MODELS_DIR",
+        help="Save JSON model files to this directory (for debugging)",
+    )
+
+    args = parser.parse_args()
+
+    # Validate: -d requires -o
+    if args.directory and not args.output_folder:
+        parser.error("-d/--directory requires -o/--output-folder")
+
+    # Determine input files and output directory
+    if args.file:
+        example_files = [args.file.resolve()]
+        screenshots_dir = args.output_folder.resolve() if args.output_folder else Path.cwd()
+    else:
+        example_files = args.directory.resolve()
+        screenshots_dir = args.output_folder.resolve()
+
+    run(
+        examples=example_files,
+        screenshots_dir=screenshots_dir,
+        headless=not args.no_headless,
+        pause=args.pause,
+        debug_models_dir=args.debug.resolve() if args.debug else None,
+    )
+
+
+if __name__ == "__main__":
+    main()