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

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

Example 2: Extract and Download Images

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

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

// 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

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:

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