ComfyUI Extension: ComfyUI Street View Loader Node

Authored by ru4ls

Created

Updated

3 stars

A custom node for ComfyUI that allows you to load images directly from Google Street View to use as backgrounds, textures, or inputs in your workflows.

Custom Nodes (0)

    README

    ComfyUI Street View Loader Node

    License: MIT Python 3.12 Version: v1.01

    A custom node for ComfyUI that allows you to load images directly from Google Street View to use as backgrounds, textures, or inputs in your workflows. Version 1.01 adds animation capabilities!

    Instead of manually taking screenshots, this node programmatically fetches a clean, high-resolution image from any location on Earth with Street View coverage, giving you precise control over the camera angle, direction, and field of view.

    Street View Loader Node

    Why Use This Node? The Power of "Ground Truth"

    While standard text-to-image models are incredible at imagining locations ("a charming street in Paris"), they struggle to recreate the exact appearance and layout of a specific, real-world place. Their output is an approximation, an artistic blend of countless images.

    This node solves that problem by providing photographic ground truth. It pulls the real, pixel-for-pixel view of a location, ensuring your generations are anchored in reality.

    This gives you the best of both worlds: the authenticity of a real photograph combined with the creative power of AI.

    Key Advantages & Use Cases

    • Guaranteed Location Accuracy: When you need the background to be recognizably your street, a specific landmark, or a favorite travel spot, this node is the only way to guarantee a 100% accurate representation.
    • The Ultimate Base for ControlNet: Feed the real Street View image into your workflow as a base for stylization (anime, oil painting), re-imagining (futuristic, historical), or precise inpainting.
    • Virtual Location Scouting: Instantly scout real-world locations from your desktop and experiment with different styles and moods for your project.
    • Personalized & Sentimental Art: Create unique art based on a place with personal meaning—a childhood home, a proposal spot, or a favorite vacation view.
    • Consistent Backgrounds for Testing: Use a consistent, real-world background to reliably test LoRAs, IPAdapters, or character models.
    • Animation Capabilities: Create smooth camera movements and parameter transitions with the new Street View Animator node (v1.01).

    Street View Loader Node combine with NanoBanana in ComfyUI

    Features

    • Direct API Integration: Pulls images directly from the Google Street View Static API.
    • Easy Workflow with URL Parser: Just find a spot on Google Maps and paste the URL.
    • Secure API Key Storage: Uses a .env file to keep your API key safe and out of your workflow files.
    • Simple Aspect Ratio Presets: Choose from common ratios like 16:9 or 1:1 without manual calculations.
    • Clean Output: No UI overlays, just the pure image.
    • Panorama Mode: Stitch multiple images together to create ultra-wide cinematic landscapes.
    • (New in v1.01) Animation Mode: Animate camera parameters over time to create smooth transitions and camera movements.

    1. Installation

    1. Navigate to your ComfyUI custom_nodes directory:

      cd ComfyUI/custom_nodes/

    2. Clone this repository:

      git clone https://github.com/ru4ls/ComfyUI_StreetView-Loader.git

    3. Install the required Python dependencies. Open a terminal, navigate to the new ComfyUI_StreetView-Loader folder, and run:

      pip install -r requirements.txt

      (This will install the requests and python-dotenv libraries required for the node to function.)

    4. Restart ComfyUI.

    2. Setup: Getting Your Google API Key (Crucial Step)

    This node requires a Google Cloud API key to function. Google provides a generous $200/month free credit, which is more than enough for extensive personal use without any charge.

    Step-by-Step Guide

    Part A: Create Project & Enable API

    1. Go to the Google Cloud Console.
    2. Create a New Project. Give it a name like ComfyUI-API.
    3. In the new project, search for "API Library".
    4. In the library, search for and Enable the "Street View Static API".

    Part B: Set Up Billing 5. You will be prompted to link a billing account. This is required, but you will not be charged unless you exceed the $200 free monthly credit.

    Part C: Create and Secure Your API Key 6. In the Cloud Console search bar, navigate to "Credentials". 7. Click "+ Create Credentials" and select "API key". 8. Copy this key immediately. 9. (IMPORTANT!) Click "Edit API key". Under "API restrictions," select "Restrict key" and add "Street View Static API" to the list. This protects your account. Click "Save".

    Part D: Configure the Node 10. In your ComfyUI/custom_nodes/ComfyUI_StreetView-Loader/ folder, create a new file named .env (or rename the existing .env.example file). 11. Open this .env file and add your copied API key in the following format: GOOGLE_STREET_VIEW_API_KEY="your_actual_api_key_goes_here" 12. Save the file. Your setup is now complete!

    3. How to Use & Upscaling

    The recommended workflow is to use the URL Parser node to feed information into the Loader node.

    1. Find your view in Google Maps and enter Street View.
    2. Frame the perfect shot, then copy the entire URL from your browser's address bar.
    3. In ComfyUI, add the Street View URL Parser node and paste the URL into it.
    4. Add the Street View Loader node.
    5. Connect the outputs of the Parser to the inputs of the Loader (location to location, etc.).

    Understanding the Nodes and Image Size Limit

    Street View URL Parser

    This node takes a full Google Maps URL as input and outputs the camera parameters (location, heading, pitch, fov).

    Street View Loader

    This is the main node that fetches the image.

    • aspect_ratio: Choose your desired output aspect ratio from the dropdown. This replaces manual width/height inputs.
    • API Limit & Upscaling: The Google Street View API has a maximum output size of 640x640 pixels. For high-resolution images (like 1080p or 4K), you must use an upscaling workflow.
    • Recommended HD Workflow:
      1. Select "16:9 Widescreen (640x360)" in the Street View Loader.
      2. Connect its IMAGE output to an Upscale Image (using model) node.
      3. Use a Load Upscale Model node (e.g., 4x-UltraSharp) to get a final, high-quality 2560x1440 image.

    4. Panoramic Loader Node

    For users who need to create wide, cinematic landscapes, the project includes the Street View Pano Loader node.

    This node overcomes the API's FOV limitations by using a sophisticated stitching algorithm. It fetches multiple overlapping image "tiles" and then uses the OpenCV library to analyze, warp, and seamlessly blend them into a single, perspective-corrected panoramic image.

    Street View Pano Loader Node in ComfyUI

    Street View Pano Loader Node result

    How to Use & Parameter Suggestions

    1. Add the "Street View Pano Loader" node to your canvas.
    2. Provide a location and center_heading (the direction you want the middle of your panorama to face).
    3. Fine-tune the parameters for a successful stitch:
      • overlap_percentage: This is the most critical setting. For OpenCV to work, it needs to see the same features in adjacent images. An overlap of 30-50% is a great starting point. If a stitch fails, increase this value first.
      • fov_per_image: A narrower Field of View (like 70-80) can reduce distortion at the edges of each tile, making it easier for the algorithm to find matching points. However, you may need to increase the num_images to capture the same total width.
      • num_images: Controls the final width of your panorama. Start with 3 and increase if needed.

    Understanding the Output: Warping & Black Borders

    A successful, high-quality stitch will not be a perfect rectangle. To correctly align the perspectives, the stitcher "warps" the flat photos onto a virtual cylinder.

    The curved edges and black borders are not an error; they are proof that the perspective correction worked! This warped image is now a seamless, geometrically correct panorama, ready for refinement.

    Refining Your Panorama: Optional Next Steps

    Once you have your stitched result, you have two great options to create a final, rectangular image:

    1. Cropping (The Simple Method)

    • Goal: To get a clean, cinematic widescreen image.
    • How: Connect the IMAGE output from the Pano Loader to a Crop node in ComfyUI. Adjust the crop box to frame the best part of the scene and remove the black areas.

    2. AI Outpainting (The Advanced Method)

    • Goal: To use AI to intelligently fill in the missing areas, creating a larger, natural-looking scene.
    • How: Feed the panoramic image into your main workflow (VAE Encode, KSampler, etc.) with a descriptive prompt of the scene and a low denoise (e.g., 0.3-0.5). The AI will use the existing pixels as a guide to generate new details in the black corners.

    Important Notes

    • API Usage: This node makes multiple API calls. A panorama with 3 images will count as 3 requests against your free monthly Google Cloud credit.
    • Stitching Process: If the OpenCV algorithm cannot find enough matching features, it will automatically fall back to a simple side-by-side stitch to ensure you always get an output. If this happens, the best solution is to increase the overlap_percentage.
    • Resolution: The output image will be very wide but only 640px tall. It is highly recommended to chain the output of this node into an Upscale Image node to increase the final resolution for your projects.

    5. Animation Node (New in v1.01)

    Version 1.01 introduces the Street View Animator node, which allows you to create animated sequences by smoothly transitioning camera parameters over time.

    This node enables you to create dynamic camera movements like slow rotations, pitch changes, or field-of-view adjustments that can be used as input for video generation workflows or simply to create smooth transitions between different viewpoints of the same location.

    Street View Animator Node in ComfyUI

    https://github.com/user-attachments/assets/7edbbdf8-2dcd-4e0c-aae0-ccc5ad1be679

    How to Use & Parameter Suggestions

    1. Add the "Street View Animator" node to your canvas.

    2. Provide a location (same as other nodes).

    3. Set your animation parameters:

      • Start/End Values: Define the beginning and ending values for heading, pitch, and fov parameters.
      • Duration & FPS: Control the total animation length and frame rate (frames per second).
      • Interpolation: Choose from different transition types (linear, ease-in, ease-out, ease-in-out) for smooth camera movements.
      • aspect_ratio: Select your desired output aspect ratio.

    4. The node will generate a sequence of images as a stacked tensor output, which can be used for:

      • Video generation workflows
      • Frame-by-frame processing
      • Creating dynamic backgrounds for animations

    Key Animation Parameters

    • Start/End Heading: Control camera rotation from start to end values (0-360 degrees)
    • Start/End Pitch: Adjust camera tilt from start to end values (-90 to 90 degrees)
    • Start/End FOV: Change field of view from start to end values (10-120 degrees)
    • Duration: Total animation time in seconds
    • FPS: Frames per second - determines smoothness and total frame count
    • Interpolation: Defines how values transition between start and end points

    Animation Tips

    • Smooth Rotations: For a full 360° rotation, set start_heading=0 and end_heading=360
    • Camera Dolly: Keep heading constant but change fov for zoom effects
    • Tilt Effects: Combine pitch changes with heading changes for dynamic camera movements
    • Frame Count: Total frames = duration × fps (higher values = smoother but may increase API usage costs)

    Important Notes

    • API Usage: This node makes multiple API calls equal to the total number of frames generated. Each frame is a separate API request.
    • Performance: Animation rendering time increases with duration and fps. Start with low settings and increase as needed.
    • Memory: Large frame sequences can consume significant memory. Consider using in smaller batches if needed.

    6. Troubleshooting

    • ValueError: API key not found: Your .env file is missing, in the wrong location, or the variable name is not GOOGLE_STREET_VIEW_API_KEY.
    • Black Image Output: This usually means Google has no Street View imagery for that coordinate, or your API key is invalid/restricted. Check your key's restrictions on the Google Cloud Console.
    • Node not appearing in ComfyUI: Ensure you have fully restarted the ComfyUI server after installation.

    License

    This project is licensed under the MIT License - see the LICENSE file for details.