v1.0
This commit is contained in:
@@ -0,0 +1,213 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user