175 lines
10 KiB
Markdown
175 lines
10 KiB
Markdown
# ComfyUI Street View Loader Node
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://www.python.org/downloads/release/python-3120/)
|
|
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
## 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.
|
|
- **(Experimental) Panorama Mode:** Stitch multiple images together to create ultra-wide cinematic landscapes.
|
|
|
|
---
|
|
|
|
## 1. Installation
|
|
|
|
1. Navigate to your ComfyUI `custom_nodes` directory:
|
|
```bash
|
|
cd ComfyUI/custom_nodes/
|
|
```
|
|
|
|
2. Clone this repository:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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](https://console.cloud.google.com/).
|
|
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](https://maps.google.com) 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.
|
|
|
|
|
|
|
|
|
|
|
|
### 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. 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](LICENSE) file for details. |