Travel Destination Brochure

Travel Destination Brochure & Video

Create travel brochures, videos, and 1-day plans for a destination city by combining OpenStreetCam street-level photos, Wikimedia Commons imagery, and VLM Run for video and copy.

Prerequisites

Before starting, ensure you have:

• Python 3.10 or higher installed
• Internet connection (for downloading images and API access)
• VLMRUN_API_KEY (optional, but required for video and travel plan generation)

No API keys required for:

• OpenStreetCam (public read access)
• Wikimedia Commons (public access)
• Nominatim geocoding (public access)

Installation Steps

Step 1: Verify Python Installation

Check if Python 3.10+ is installed:

Windows (PowerShell):

python --version
# Should show Python 3.10.x or higher

macOS/Linux:

python3 --version
# Should show Python 3.10.x or higher

If Python is not installed or is an older version:

• Windows: Download from python.org
• macOS: brew install python@3.11 (or use python.org installer)
• Linux: sudo apt install python3.11 (Ubuntu/Debian) or use your distribution's package manager

Step 2: Install uv (Package Manager)

Windows (PowerShell):

# Using pip
pip install uv

# Or using PowerShell installer
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

# Using pip
pip install uv

# Or using curl installer
curl -LsSf https://astral.sh/uv/install.sh | sh

Verify installation:

uv --version

Step 3: Create Virtual Environment

Navigate to the skill directory and create a virtual environment:

Windows (PowerShell):

cd c:\Users\mehed\.claude\skills\travel-destination-brochure
uv venv
.venv\Scripts\Activate.ps1

macOS/Linux:

cd ~/.claude/skills/travel-destination-brochure
uv venv
source .venv/bin/activate

Note: You should see (.venv) in your terminal prompt when activated.

Step 4: Install Dependencies

Install the required packages:

# Install vlmrun CLI (required for video and travel plan generation)
uv pip install "vlmrun[cli]"

# Install requests (required for API calls)
uv pip install requests

Verify installation:

vlmrun --version
python -c "import requests; print(requests.__version__)"

Step 5: Set Up VLMRUN_API_KEY (Optional but Recommended)

To generate travel videos and plans, you need a VLMRUN API key:

Windows (PowerShell):

# Set for current session
Check .env file for api key

$env:VLMRUN_API_KEY="your-api-key-here"

# Set permanently (User-level)
[System.Environment]::SetEnvironmentVariable('VLMRUN_API_KEY', 'your-api-key-here', 'User')

macOS/Linux:

# Set for current session
export VLMRUN_API_KEY="your-api-key-here"

# Set permanently (add to ~/.bashrc or ~/.zshrc)
echo 'export VLMRUN_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Verify environment variable:

Read .env file to find api keys

# Windows PowerShell
echo $env:VLMRUN_API_KEY

# macOS/Linux
echo $VLMRUN_API_KEY

Step 6: Verify Installation

Test that everything works:

# Test geocoding (should work without API key)
uv run scripts/geocode_city.py "Paris, France"

# Test vlmrun (if API key is set)
vlmrun --help

Installation Complete! You're ready to generate travel brochures.

Quick Start (Recommended)

Use the simplified all-in-one script that handles everything automatically:

Windows (PowerShell):

uv run scripts/simple_travel_brochure.py --city "Doha, Qatar"

macOS/Linux:

uv run scripts/simple_travel_brochure.py --city "Doha, Qatar"

Alternative (if uv is not available):

python scripts/simple_travel_brochure.py --city "Doha, Qatar"

This script will:

1. Geocode the city name to coordinates
2. Fetch 3 street-level photos from OpenStreetCam
3. Fetch 2 landmark images from Wikimedia Commons (total 5 images)
4. Generate a 30-second travel video using vlmrun (if VLMRUN_API_KEY is set)
5. Generate a one-day travel plan using vlmrun (if VLMRUN_API_KEY is set)
6. Clean up temporary files automatically

Options:

• --output DIR — Output directory (default: ./travel_brochure)
• --osc-count N — Number of OpenStreetCam photos (default: 3)
• --commons-count N — Number of Commons images (default: 2)

Note: Set the VLMRUN_API_KEY environment variable to enable video and travel plan generation. The script will skip video generation gracefully if the API key is not set.

Example:

uv run scripts/simple_travel_brochure.py --city "Paris, France" --output ./paris_trip

Output:

• images/ — Downloaded photos (5 images total)
• manifest.json — Metadata about the city, coordinates, and image paths
• video/ — Generated travel video (if VLMRUN_API_KEY is set)
• travel_plan.md — One-day travel itinerary (if VLMRUN_API_KEY is set)

Advanced: Step-by-Step Workflow

For more control over each step, use the individual scripts below.

Workflow Overview

1. Collect input – Get destination city from the user.
2. Geocode – Resolve city name to coordinates (lat, lng).
3. Fetch imagery & info – OpenStreetCam (nearby photos) + Wikimedia Commons (search images and metadata).
4. Generate assets – Use vlmrun to create a short travel video and a travel plan from the collected images and info.

All paths below are relative to the directory containing this SKILL.md.

Run scripts using:

• uv run scripts/script_name.py (recommended - handles dependencies automatically via PEP 723)
• python scripts/script_name.py (if dependencies are already installed)

Step 1: Get Destination City

Ask the user: "Which city do you want the travel brochure and video for?" Use the exact city name (and country/region if ambiguous) for geocoding and Commons search.

Step 2: Geocode City

Resolve city name to latitude/longitude (e.g. for OpenStreetCam and optional Commons geo-search).

uv run scripts/geocode_city.py "Paris, France"
# Or: python scripts/geocode_city.py "Tokyo"

Output: JSON with lat, lng, display_name. Use these in Steps 3–4.

Step 3: Fetch OpenStreetCam Photos

OpenStreetCam provides street-level imagery. Base URL: https://api.openstreetcam.org/.

• Nearby sequences: POST /nearby-tracks — body: lat, lng, distance (km).
• Nearby photos: POST /1.0/list/nearby-photos/ — body: lat, lng, radius (meters), optional page, ipp.

No access_token required for these read endpoints. Use scripts/fetch_openstreetcam.py to request photos and optionally download thumbnails/full images into a folder.

uv run scripts/fetch_openstreetcam.py --lat 48.8566 --lng 2.3522 --radius 2000 --output ./assets/osc --max-photos 20

Produces: image files under --output and a small manifest (e.g. osc_manifest.json) with captions/locations if available.

Step 4: Fetch Wikimedia Commons Images & Info

Commons provides landmark and cultural images. API: https://commons.wikimedia.org/w/api.php.

• Search: action=query, list=search, srsearch=<city or landmark>, srnamespace=6 (File namespace).
• Image URLs and metadata: action=query, prop=imageinfo, iiprop=url|extmetadata, titles=File:....

Use scripts/fetch_commons.py to search by destination name, resolve file URLs, and optionally download to a folder.

uv run scripts/fetch_commons.py --query "Paris landmarks" --output ./assets/commons --max-images 15

Produces: image files and a manifest (e.g. commons_manifest.json) with captions/descriptions from Commons.

Step 5: Aggregate Manifest for vlmrun

Combine OSC and Commons manifests (and optionally add short text lines per image) into a single manifest or list that you can pass to vlmrun (e.g. paths + one short caption per image). The pipeline script can do this.

uv run scripts/run_travel_pipeline.py --city "Paris, France" --output-dir ./travel_output

This script should: geocode → fetch OSC → fetch Commons → write images/ and manifest.json (or manifest.txt) under --output-dir.

Step 6: Generate Video and Travel Plan with vlmrun

Use the vlmrun-cli-skill workflow: ensure vlmrun is installed and VLMRUN_API_KEY is set.

Travel video – Pass the collected images and a single prompt so the model produces a short travel video (e.g. 30 seconds). Prefer -o to save the artifact.

Note: If VLMRUN_API_KEY is set as an environment variable, you can omit --api-key:

# Using environment variable (recommended)
vlmrun chat "Create a 30-second travel video showcasing these images of [CITY]. Add subtle captions with the location names. Keep a calm, inspiring travel-documentary style." -i ./travel_output/images/photo1.jpg -i ./travel_output/images/photo2.jpg -i ./travel_output/images/photo3.jpg ... -o ./travel_output/video

# Or using --api-key from .env, flag directly
vlmrun --api-key "your-api-key-here" chat "Create a 30-second travel video showcasing these images of [CITY]. Add subtle captions with the location names. Keep a calm, inspiring travel-documentary style." -i ./travel_output/images/photo1.jpg -i ./travel_output/images/photo2.jpg -i ./travel_output/images/photo3.jpg ... -o ./travel_output/video

If the number of files is large, reference the manifest and pass a subset (e.g. up to 10–15 representative images) or use a prompt that says “using the attached images in order.”

Travel plan (1-day) – Use the same images plus a text prompt to get a narrative or bullet-point plan.

# Using environment variable (recommended)
vlmrun chat "Using these images and their locations, write a one-day travel plan for [CITY]: morning, midday, and evening activities with specific places and practical tips. Output as structured markdown (headings and bullet points)." -i ./travel_output/images/photo1.jpg -i ./travel_output/images/photo2.jpg ... -o ./travel_output

# Or using --api-key flag directly
vlmrun --api-key "your-api-key-here" chat "Using these images and their locations, write a one-day travel plan for [CITY]: morning, midday, and evening activities with specific places and practical tips. Output as structured markdown (headings and bullet points)." -i ./travel_output/images/photo1.jpg -i ./travel_output/images/photo2.jpg ... -o ./travel_output

Save the model’s text response (and any artifact) under --output-dir (e.g. travel_plan.md).

Scripts Reference

API References

• OpenStreetCam: API Reference — nearby-tracks, list/nearby-photos, auth only for uploads.
• Wikimedia Commons: Commons API — action=query, list=search, prop=imageinfo; MediaWiki API help.
• vlmrun: Use the vlmrun-cli-skill for setup, env vars, and all vlmrun chat options.

Checklist for a Complete Run

• User provided destination city (and country if needed).
• Geocoded city and confirmed lat/lng.
• Fetched OpenStreetCam photos; saved images and manifest.
• Fetched Commons images for the destination; saved images and manifest.
• Built aggregated manifest/images under one output dir.
• Ran vlmrun with collected images to generate travel video; saved artifact with -o.
• Ran vlmrun with same (or subset) images to generate travel plan; saved text as markdown.

Troubleshooting

Installation Issues

Python not found:

• Windows: Ensure Python is added to PATH during installation, or use py instead of python
• macOS/Linux: Use python3 instead of python

uv command not found:

• Restart your terminal after installation
• Windows: Check if uv is in your PATH: $env:PATH
• macOS/Linux: Ensure ~/.cargo/bin or ~/.local/bin is in your PATH

Virtual environment activation fails:

• Windows PowerShell: If you get an execution policy error, run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
• Windows CMD: Use .venv\Scripts\activate.bat instead of .ps1
• macOS/Linux: Ensure you're using source .venv/bin/activate (not ./.venv/bin/activate)

vlmrun not found:

• Ensure virtual environment is activated
• Reinstall: uv pip install "vlmrun[cli]"
• Verify: which vlmrun (macOS/Linux) or where.exe vlmrun (Windows)

Runtime Issues

• Geocode fails – Try adding country/region, or use “City, Country” format.
• OpenStreetCam returns few/no results:
• Increase radius parameter (default: 2000m, try 5000m or 10000m)
• Try city center coordinates instead of outskirts
• Some regions have sparse coverage; try nearby major cities
• Commons returns few results – Broaden query (e.g. “City tourism”, “City sights”).
• vlmrun errors:
• Confirm VLMRUN_API_KEY is set correctly: echo $VLMRUN_API_KEY (macOS/Linux) or echo $env:VLMRUN_API_KEY (Windows)
• Check network connection
• Reduce number of input images if hitting API limits (try 5-10 images instead of 20+)
• Verify API key is valid and has sufficient credits/quota

Script execution errors:

• Ensure you're in the correct directory (skill root directory)
• Check that virtual environment is activated
• Verify all dependencies are installed: uv pip list

Example End-to-End

# 1) Ask user for city, then run pipeline (e.g. "Paris, France")
uv run scripts/run_travel_pipeline.py --city "Paris, France" --output-dir ./travel_output

# 2) Generate travel video (use image paths from travel_output/images/ or image_paths.txt)
vlmrun chat "Create a 30-second travel video from these images of Paris. Add short location captions. Calm documentary style." -i ./travel_output/images/img_0000.jpg -i ./travel_output/images/img_0001.jpg -o ./travel_output/video

# 3) Generate 1-day travel plan (same images)
vlmrun chat "Using these photos of Paris, write a one-day travel plan (morning, midday, evening) with specific places and tips in markdown." -i ./travel_output/images/img_0000.jpg -i ./travel_output/images/img_0001.jpg -o ./travel_output

Quick Reference: Key URLs

• OpenStreetCam API base: https://api.openstreetcam.org/
• Commons API: https://commons.wikimedia.org/w/api.php
• Nominatim geocoding: https://nominatim.openstreetmap.org/search?q=<query>&format=json