# Sc## What it shows

1. **Original image with bounding boxes** - Shows the input image with colored rectangles indicating regions identified by the LLM vision model
2. **Cropped regions** - Displays each cropped region in a grid layout, showing what areas are processed for detailed detection
3. **Segmentation within bounding boxes** - Shows segmentation masks cropped to their corresponding bounding box regions, displaying the precise object boundaries detected by Grounded-SAM-2 within each region
4. **Mask overlays** - Shows all detected masks overlaid on the original image with transparencyd Zoom Visualization Tool

This tool visualizes the scout-and-zoom process used in the anonymization pipeline, showing how bounding boxes from LLM vision analysis are used to crop regions for precise object detection.

## What it shows

1. **Original image with bounding boxes** - Shows the input image with colored rectangles indicating regions identified by the LLM vision model
2. **Cropped regions** - Displays each cropped region in a grid layout, showing what areas are processed for detailed detection
3. **Segmentation masks** - Shows individual segmentation masks in a grid, displaying the precise object boundaries detected by Grounded-SAM-2
4. **Mask overlays** - Shows all detected masks overlaid on the original image with transparency

## Usage

### Basic usage with bounding boxes

```bash
python tools/visualize_scout_zoom.py path/to/image.png '[{"bbox": [x, y, w, h], "description": "text"}, ...]'
```

### With mask overlays

```bash
python tools/visualize_scout_zoom.py path/to/image.png bboxes.json --masks mask1.png mask2.png --output-dir ./viz
```

### From Python code

```python
from tools.visualize_scout_zoom import create_comprehensive_visualization

bboxes = [
    {"bbox": [100, 200, 150, 100], "description": "Store sign"},
    {"bbox": [300, 400, 200, 80], "description": "Business card"}
]

output_files = create_comprehensive_visualization(
    "image.png",
    bboxes,
    mask_paths=["mask1.png", "mask2.png"],
    output_dir="artifacts/visualizations"
)
```

## Parameters

- `image_path`: Path to the input image
- `bboxes_json`: JSON string or file path containing bounding box data
- `--masks`: Optional list of mask file paths to overlay
- `--output-dir`: Directory to save visualization files (defaults to image directory)
- `--show`: Display plots interactively instead of saving

## Bounding Box Format

Bounding boxes should be in the format `[x, y, width, height]` where:
- `x, y`: Top-left coordinates
- `width, height`: Dimensions of the rectangle

Example JSON:
```json
[
  {
    "bbox": [465, 248, 525, 345],
    "description": "Poster on storefront window",
    "det_prompt": "advertisement poster with text."
  }
]
```

## Output Files

The tool generates four types of visualizations:

1. `*_bboxes.png` - Original image with bounding box overlays
2. `*_crops.png` - Grid of cropped regions
3. `*_segmentation.png` - Segmentation masks cropped to their bounding box regions with coverage percentages
4. `*_masks.png` - Image with all mask overlays combined

## Example

Run the example script:

```bash
python tools/example_scout_zoom_viz.py
```

This will create visualizations for sample data from the pipeline, using real mask files from previous anonymization runs stored in `artifacts/other/masks/`.

## Troubleshooting

### "No valid mask files found" in segmentation visualization

This happens when the mask file paths don't exist. Solutions:

1. **Check mask file paths**: Ensure the mask files exist at the specified locations
2. **Use wildcards**: Use `artifacts/other/masks/*.png` to include all mask files
3. **Run pipeline first**: Make sure you've run the anonymization pipeline to generate masks
4. **Check artifacts directory**: Masks are stored in `artifacts/{relative_path}/masks/`

Example with existing masks:
```bash
python tools/visualize_scout_zoom.py image.png bboxes.json \
  --masks artifacts/other/masks/*.png
```