From 0a2b9d3e35ad4872200692935acddd756da2bea5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 2 Dec 2025 02:15:34 +0000 Subject: [PATCH 1/2] Initial plan From a8b7a1743c562e41cefc80516dce1c25391be3db Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 2 Dec 2025 02:21:48 +0000 Subject: [PATCH 2/2] Add comprehensive batch screenshot documentation Co-authored-by: wdconinc <4656391+wdconinc@users.noreply.github.com> --- doc/pyrobird.md | 217 +++++++++++++++++++++++++++++++++++++++++++++ pyrobird/README.md | 217 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 434 insertions(+) diff --git a/doc/pyrobird.md b/doc/pyrobird.md index 0c49dce..3d3548f 100644 --- a/doc/pyrobird.md +++ b/doc/pyrobird.md @@ -125,6 +125,223 @@ has access to files in your current directory or a directory provided via `--wor the file `/home/username/datafiles/filename.root` will be opened +## Batch Screenshots + +The `pyrobird screenshot` command allows you to capture screenshots of Firebird visualizations in batch mode. This is particularly useful for: + +- Generating visualizations for publications and presentations +- Creating automated documentation of event displays +- Batch processing multiple events for comparison +- Quality assurance and validation workflows + +### Installation + +To use the screenshot functionality, you need to install pyrobird with the `batch` optional dependency: + +```bash +pip install pyrobird[batch] +``` + +After installing, you need to install the Chromium browser binaries used by Playwright: + +```bash +python -m playwright install chromium +``` + +> **Note**: On the first run, Playwright will download Chromium (~100MB) if it's not already installed on your system. + +### Basic Usage + +The simplest way to capture a screenshot: + +```bash +pyrobird screenshot +``` + +This command will: +1. Start a local Firebird server on `http://localhost:5454` +2. Wait for the page to load +3. Capture a full-page screenshot +4. Save it to `screenshots/screenshot.png` +5. Automatically shut down the server + +Screenshots are saved in a `screenshots/` directory with automatic numbering to prevent overwrites. + +### Command Options + +The screenshot command accepts several options to customize its behavior: + +| Option | Type | Default | Description | +|----------------------------|---------|-----------------------|---------------------------------------------------------------------------------------------------------------| +| `--url TEXT` | String | `http://localhost:5454` | URL to take the screenshot of. Use this if you want to screenshot a specific page or event. | +| `--output-path TEXT` | String | `screenshot.png` | Base filename for the screenshot. Will be saved in `screenshots/` directory with auto-numbering if file exists. | +| `--work-path TEXT` | String | Current directory | Set the base directory path for file downloads. Files in Firebird will be loaded relative to this path. | +| `--unsecure-files` | Flag | `False` | Allow unrestricted file downloads. Use with caution - see security notes in the serve section. | +| `--allow-cors` | Flag | `False` | Enable CORS for downloaded files. | +| `--disable-download` | Flag | `False` | Disable all file downloads from the server. | + +### Examples + +#### 1. Basic Screenshot with Custom Output Name + +```bash +pyrobird screenshot --output-path event_001.png +``` + +This saves the screenshot as `screenshots/event_001.png` (or `screenshots/event_001_001.png` if the file already exists). + +#### 2. Screenshot with Custom Data Directory + +```bash +pyrobird screenshot --work-path=/path/to/data --output-path detector_view.png +``` + +This allows Firebird to access files in `/path/to/data` when loading event data. + +#### 3. Screenshot a Specific Event + +First, ensure your data file is accessible, then use a URL that opens a specific event: + +```bash +pyrobird screenshot --work-path=/path/to/data \ + --url "http://localhost:5454/#/event?file=local://mydata.root&event=5" \ + --output-path event_5.png +``` + +#### 4. Batch Processing Multiple Events + +You can create a simple shell script to process multiple events: + +```bash +#!/bin/bash +# batch_screenshots.sh + +DATA_PATH="/path/to/data" +DATA_FILE="myevents.root" + +for event in {0..9}; do + pyrobird screenshot \ + --work-path="$DATA_PATH" \ + --url "http://localhost:5454/#/event?file=local://$DATA_FILE&event=$event" \ + --output-path "event_${event}.png" + + echo "Captured screenshot for event $event" +done +``` + +Make the script executable and run it: + +```bash +chmod +x batch_screenshots.sh +./batch_screenshots.sh +``` + +#### 5. Screenshot with Different Server Configurations + +If you need to allow access to files outside the working directory: + +```bash +pyrobird screenshot --unsecure-files --output-path system_files.png +``` + +> **Warning**: Use `--unsecure-files` only on trusted personal machines. Never use in production or shared environments. + +### Screenshot Configuration + +The screenshot functionality uses the following default settings: + +- **Viewport Size**: 1920x1080 pixels (Full HD) +- **Page Mode**: Full page screenshot (captures entire scrollable content) +- **Wait Strategy**: Waits for DOM content loaded (up to 10 seconds) +- **Additional Wait**: 2 seconds after page load to ensure rendering completes +- **Browser**: Headless Chromium + +These settings are optimized for high-quality event display captures but are currently hardcoded in the implementation. + +### Output Directory Structure + +Screenshots are automatically organized in a `screenshots/` directory with smart numbering: + +``` +screenshots/ +├── screenshot.png # First screenshot +├── event_001.png # First screenshot with custom name +├── event_001_001.png # Second screenshot with same name (auto-numbered) +├── event_001_002.png # Third screenshot with same name +└── detector_view.png # Another screenshot +``` + +The auto-numbering system: +- If `filename.png` doesn't exist, it's created as-is +- If it exists, the next available number is found (e.g., `filename_001.png`) +- Numbering continues sequentially even if there are gaps + +### Troubleshooting + +#### Playwright Not Installed + +If you see an error about Playwright not being installed: + +```bash +pip install playwright +python -m playwright install chromium +``` + +#### Server Won't Start + +If the Flask server fails to start, check if port 5454 is already in use: + +```bash +# On Linux/Mac +lsof -i :5454 + +# Kill the process if needed +kill -9 +``` + +#### Screenshots Are Black or Incomplete + +If screenshots appear black or don't show the expected content: + +1. The page might need more time to render. The command waits 2 seconds after page load, but complex visualizations might need longer. +2. Try taking a screenshot manually first to verify the URL works correctly. +3. Check that your data files are accessible from the `--work-path` directory. + +#### Permission Errors + +If you get permission errors when accessing files: + +1. Make sure the `--work-path` includes all necessary data files +2. Check file permissions on your data files +3. Consider using `--unsecure-files` for testing (on personal machines only) + +### Advanced: Programmatic Usage + +You can also use the screenshot functionality programmatically in Python: + +```python +from pyrobird.cli.screenshot import capture_screenshot, get_screenshot_path + +# Generate unique output path +output_path = get_screenshot_path("my_event.png") + +# Capture screenshot (requires server to be running) +capture_screenshot("http://localhost:5454/#/event?file=local://data.root&event=5", output_path) + +print(f"Screenshot saved to {output_path}") +``` + +> **Note**: When using programmatically, you need to manage the Flask server lifecycle yourself. + +### Tips for Best Results + +1. **Consistent Naming**: Use descriptive names that include event numbers or identifiers +2. **Batch Processing**: Write scripts to automate screenshot capture for multiple events +3. **Resolution**: The default 1920x1080 viewport provides good quality for most purposes +4. **Data Organization**: Keep your data files organized and use `--work-path` to point to the correct directory +5. **Preview First**: Manually check one or two events in the browser before running batch operations + + ## API Documentation This is technical explanation of what is under the hood of the server part diff --git a/pyrobird/README.md b/pyrobird/README.md index 29655ea..db5a948 100644 --- a/pyrobird/README.md +++ b/pyrobird/README.md @@ -137,6 +137,223 @@ has access to files in your current directory or a directory provided via `--wor the file `/home/username/datafiles/filename.root` will be opened +## Batch Screenshots + +The `pyrobird screenshot` command allows you to capture screenshots of Firebird visualizations in batch mode. This is particularly useful for: + +- Generating visualizations for publications and presentations +- Creating automated documentation of event displays +- Batch processing multiple events for comparison +- Quality assurance and validation workflows + +### Installation + +To use the screenshot functionality, you need to install pyrobird with the `batch` optional dependency: + +```bash +pip install pyrobird[batch] +``` + +After installing, you need to install the Chromium browser binaries used by Playwright: + +```bash +python -m playwright install chromium +``` + +> **Note**: On the first run, Playwright will download Chromium (~100MB) if it's not already installed on your system. + +### Basic Usage + +The simplest way to capture a screenshot: + +```bash +pyrobird screenshot +``` + +This command will: +1. Start a local Firebird server on `http://localhost:5454` +2. Wait for the page to load +3. Capture a full-page screenshot +4. Save it to `screenshots/screenshot.png` +5. Automatically shut down the server + +Screenshots are saved in a `screenshots/` directory with automatic numbering to prevent overwrites. + +### Command Options + +The screenshot command accepts several options to customize its behavior: + +| Option | Type | Default | Description | +|----------------------------|---------|-----------------------|---------------------------------------------------------------------------------------------------------------| +| `--url TEXT` | String | `http://localhost:5454` | URL to take the screenshot of. Use this if you want to screenshot a specific page or event. | +| `--output-path TEXT` | String | `screenshot.png` | Base filename for the screenshot. Will be saved in `screenshots/` directory with auto-numbering if file exists. | +| `--work-path TEXT` | String | Current directory | Set the base directory path for file downloads. Files in Firebird will be loaded relative to this path. | +| `--unsecure-files` | Flag | `False` | Allow unrestricted file downloads. Use with caution - see security notes in the serve section. | +| `--allow-cors` | Flag | `False` | Enable CORS for downloaded files. | +| `--disable-download` | Flag | `False` | Disable all file downloads from the server. | + +### Examples + +#### 1. Basic Screenshot with Custom Output Name + +```bash +pyrobird screenshot --output-path event_001.png +``` + +This saves the screenshot as `screenshots/event_001.png` (or `screenshots/event_001_001.png` if the file already exists). + +#### 2. Screenshot with Custom Data Directory + +```bash +pyrobird screenshot --work-path=/path/to/data --output-path detector_view.png +``` + +This allows Firebird to access files in `/path/to/data` when loading event data. + +#### 3. Screenshot a Specific Event + +First, ensure your data file is accessible, then use a URL that opens a specific event: + +```bash +pyrobird screenshot --work-path=/path/to/data \ + --url "http://localhost:5454/#/event?file=local://mydata.root&event=5" \ + --output-path event_5.png +``` + +#### 4. Batch Processing Multiple Events + +You can create a simple shell script to process multiple events: + +```bash +#!/bin/bash +# batch_screenshots.sh + +DATA_PATH="/path/to/data" +DATA_FILE="myevents.root" + +for event in {0..9}; do + pyrobird screenshot \ + --work-path="$DATA_PATH" \ + --url "http://localhost:5454/#/event?file=local://$DATA_FILE&event=$event" \ + --output-path "event_${event}.png" + + echo "Captured screenshot for event $event" +done +``` + +Make the script executable and run it: + +```bash +chmod +x batch_screenshots.sh +./batch_screenshots.sh +``` + +#### 5. Screenshot with Different Server Configurations + +If you need to allow access to files outside the working directory: + +```bash +pyrobird screenshot --unsecure-files --output-path system_files.png +``` + +> **Warning**: Use `--unsecure-files` only on trusted personal machines. Never use in production or shared environments. + +### Screenshot Configuration + +The screenshot functionality uses the following default settings: + +- **Viewport Size**: 1920x1080 pixels (Full HD) +- **Page Mode**: Full page screenshot (captures entire scrollable content) +- **Wait Strategy**: Waits for DOM content loaded (up to 10 seconds) +- **Additional Wait**: 2 seconds after page load to ensure rendering completes +- **Browser**: Headless Chromium + +These settings are optimized for high-quality event display captures but are currently hardcoded in the implementation. + +### Output Directory Structure + +Screenshots are automatically organized in a `screenshots/` directory with smart numbering: + +``` +screenshots/ +├── screenshot.png # First screenshot +├── event_001.png # First screenshot with custom name +├── event_001_001.png # Second screenshot with same name (auto-numbered) +├── event_001_002.png # Third screenshot with same name +└── detector_view.png # Another screenshot +``` + +The auto-numbering system: +- If `filename.png` doesn't exist, it's created as-is +- If it exists, the next available number is found (e.g., `filename_001.png`) +- Numbering continues sequentially even if there are gaps + +### Troubleshooting + +#### Playwright Not Installed + +If you see an error about Playwright not being installed: + +```bash +pip install playwright +python -m playwright install chromium +``` + +#### Server Won't Start + +If the Flask server fails to start, check if port 5454 is already in use: + +```bash +# On Linux/Mac +lsof -i :5454 + +# Kill the process if needed +kill -9 +``` + +#### Screenshots Are Black or Incomplete + +If screenshots appear black or don't show the expected content: + +1. The page might need more time to render. The command waits 2 seconds after page load, but complex visualizations might need longer. +2. Try taking a screenshot manually first to verify the URL works correctly. +3. Check that your data files are accessible from the `--work-path` directory. + +#### Permission Errors + +If you get permission errors when accessing files: + +1. Make sure the `--work-path` includes all necessary data files +2. Check file permissions on your data files +3. Consider using `--unsecure-files` for testing (on personal machines only) + +### Advanced: Programmatic Usage + +You can also use the screenshot functionality programmatically in Python: + +```python +from pyrobird.cli.screenshot import capture_screenshot, get_screenshot_path + +# Generate unique output path +output_path = get_screenshot_path("my_event.png") + +# Capture screenshot (requires server to be running) +capture_screenshot("http://localhost:5454/#/event?file=local://data.root&event=5", output_path) + +print(f"Screenshot saved to {output_path}") +``` + +> **Note**: When using programmatically, you need to manage the Flask server lifecycle yourself. + +### Tips for Best Results + +1. **Consistent Naming**: Use descriptive names that include event numbers or identifiers +2. **Batch Processing**: Write scripts to automate screenshot capture for multiple events +3. **Resolution**: The default 1920x1080 viewport provides good quality for most purposes +4. **Data Organization**: Keep your data files organized and use `--work-path` to point to the correct directory +5. **Preview First**: Manually check one or two events in the browser before running batch operations + + ## API Documentation This is technical explanation of what is under the hood of the server part