homeclaw/BROWSER_GET_IMAGES_GUIDE.md

# Browser Get Images Tool Guide

## Overview

The `browser_get_images` tool is a powerful new feature in SmallClaw v3.1 that allows you to extract, download, and analyze images from web pages using Playwright browser automation.

## Features

### Core Capabilities
- ✅ **Extract images** from any webpage
- ✅ **Filter by type** (jpg, png, webp, gif, etc.)
- ✅ **Filter by size** (min/max bytes)
- ✅ **Download images** to workspace
- ✅ **Extract metadata** (dimensions, alt text, title)
- ✅ **Save metadata** to JSON file
- ✅ **Handle large pages** efficiently

### Image Metadata
For each extracted image, you get:
- **URL**: The image source URL
- **Type**: File extension (jpg, png, webp, gif)
- **Size**: File size in bytes
- **Width**: Image width in pixels
- **Height**: Image height in pixels
- **Alt**: Alt text (if available)
- **Title**: Title attribute (if available)
- **Loading**: Loading attribute (if available)

## Usage Examples

### Example 1: Basic Image Extraction

```typescript
const result = await browserGetImages('session-id', {
  url: 'https://example.com',
  max_images: 50,
  download: false,
  save_metadata: false,
});
```

### Example 2: Extract and Download Images

```typescript
const result = await browserGetImages('session-id', {
  url: 'https://example.com',
  max_images: 10,
  image_types: ['jpg', 'png'],
  min_size: 1000,
  max_size: 5000000,
  download: true,
  save_metadata: true,
});
```

### Example 3: Extract Large Images Only

```typescript
const result = await browserGetImages('session-id', {
  url: 'https://example.com',
  max_images: 20,
  min_size: 1048576, // 1MB
  max_size: 10485760, // 10MB
  image_types: ['jpg', 'png', 'webp'],
  download: false,
  save_metadata: false,
});
```

### Example 4: Extract from Current Page

```typescript
// First open the page
await browserOpen('session-id', 'https://example.com');

// Then extract images from current page
const result = await browserGetImages('session-id', {
  max_images: 30,
  download: false,
  save_metadata: false,
});
```

### Example 5: Extract Specific Image Types

```typescript
const result = await browserGetImages('session-id', {
  url: 'https://example.com',
  max_images: 50,
  image_types: ['jpg', 'png', 'webp'], // Only these types
  download: false,
  save_metadata: false,
});
```

## Parameters

### Required Parameters
None - all parameters are optional.

### Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `url` | string | Optional | URL of the page to extract images from. If not provided, uses current page. |
| `max_images` | number | 50 | Maximum number of images to return. Range: 1-100. |
| `min_size` | number | 0 | Minimum image size in bytes. Range: 0-∞. |
| `max_size` | number | 10485760 (10MB) | Maximum image size in bytes. Range: 0-∞. |
| `image_types` | string[] | ['jpg', 'jpeg', 'png', 'webp', 'gif'] | Array of image types to include. |
| `download` | boolean | false | If true, downloads images to workspace/uploads/. |
| `save_metadata` | boolean | false | If true, saves metadata to JSON file. |

## Return Format

The tool returns a formatted string with:
1. Summary of extracted images count
2. Image types found
3. Total size
4. List of images with metadata
5. Download status (if applicable)
6. Metadata file path (if applicable)

### Example Output

```
✓ Found 12 images from https://example.com
  Types: jpg, png, webp
  Total size: 2.45 MB

Image List:
  - [jpg] https://example.com/image1.jpg
    Size: 125,000 bytes, 800x600px
    Alt: "Example image"
  - [png] https://example.com/image2.png
    Size: 89,000 bytes, 1920x1080px
  - [webp] https://example.com/image3.webp
    Size: 45,000 bytes, 400x300px
  ... and 9 more images

✓ Downloaded 3 images to workspace/uploads/
✓ Metadata saved to C:\Users\kimsg\.smallclaw\downloads\image_metadata.json
```

## Performance Characteristics

- **Navigation Time**: ~3-4 seconds (if URL provided)
- **Extraction Time**: ~1-2 seconds per page
- **Download Time**: ~0.5-1 second per image (10 images = ~5-10 seconds)
- **Memory Usage**: Low (subprocess-based)
- **Total Time**: ~5-15 seconds per page (with downloads)

## Best Practices

1. **Be Specific**: Use specific URLs and filters to get relevant images
2. **Limit Downloads**: Set `download: false` for quick extraction, enable only when needed
3. **Use Filters**: Filter by size and type to reduce noise
4. **Batch Processing**: Extract from multiple pages in sequence
5. **Handle Errors**: Check for errors in the result string

## Limitations

- Requires Playwright to be installed
- May not work on sites with complex JavaScript rendering
- Downloads are limited to 10 images per call (performance)
- Image size is estimated (actual size requires fetch)
- Some images may be blocked by CORS

## Comparison with Subagent Approach

### browser_get_images Tool
✅ Direct integration with browser automation
✅ Faster extraction (no subagent overhead)
✅ Can download images
✅ Extracts metadata
✅ Works with JavaScript-rendered sites

### image_extractor_v1 Subagent
✅ Works with any URL (no browser needed)
✅ Can extract from multiple pages
✅ No Playwright dependency
✅ Good for static HTML pages

## Use Cases

1. **Image Collection**: Gather images from multiple pages
2. **Image Analysis**: Extract images for AI analysis
3. **Content Scraping**: Collect visual content from websites
4. **Research**: Gather images for research purposes
5. **Backup**: Download images for offline access

## Testing

Run the test suite:
```bash
npx tsx tests/test-browser-get-images.ts
```

## Files

- `src/gateway/browser-tools.ts` - Implementation
- `tests/test-browser-get-images.ts` - Test suite
- `BROWSER_GET_IMAGES_GUIDE.md` - This guide

## Future Enhancements

Potential improvements:
- Parallel image downloading
- Image compression
- Image format conversion
- Advanced filtering (aspect ratio, color palette)
- Image similarity search
- Batch processing with progress tracking
- Image preview generation