streetview-tools 0.1.0__tar.gz

streetview_tools-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build artifacts
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db

streetview_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AngLaboratory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

streetview_tools-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: streetview-tools
+Version: 0.1.0
+Summary: Retrieve street-view panorama metadata and download panorama images
+Project-URL: Homepage, https://github.com/AngLaboratory/streetview-tools
+Project-URL: Source, https://github.com/AngLaboratory/streetview-tools
+Project-URL: Issues, https://github.com/AngLaboratory/streetview-tools/issues
+Author-email: AngLaboratory <anglaboratory@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: panoid,panorama,roadview,street-view,streetview
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Requires-Dist: pillow>=9.0
+Requires-Dist: py360convert>=1.0.4
+Requires-Dist: requests>=2.25
+Description-Content-Type: text/markdown
+
+# streetview-tools
+
+Retrieve panorama metadata and download panorama images from Google Street View,
+Naver Roadview, and Kakao Roadview.
+
+## Installation
+
+```bash
+pip install streetview-tools
+```
+
+## Usage
+
+```python
+from streetview_tools import google
+
+pano = google.get_pano_info(panoid="PANORAMA_ID")
+google.save_img(
+	panoid="PANORAMA_ID",
+	file_name="output.png",
+	width=2048,
+)
+```
+
+The same functions are available from `streetview_tools.naver` and
+`streetview_tools.kakao`.
+
+Google and Kakao also provide `save_img_face()` for saving a square direction
+crop from their equirectangular panorama images. The supported directions are
+`l`, `f`, `r`, `b`, `d`, and `u`, and the default filename is
+`PANORAMA_ID_<direction>.png`.
+
+For Naver cubic panoramas, a single direction can be saved as a square image:
+
+```python
+from streetview_tools import naver
+
+naver.save_img_face(
+	panoid="PANORAMA_ID",
+	direction="u",
+	width=800,
+)
+# PANORAMA_ID_u.png
+```
+
+Valid directions are `l`, `f`, `r`, `b`, `d`, and `u`. A direction can also be
+provided as a list, which returns or saves one image per direction:
+
+```python
+images = naver.get_img_face(
+	panoid="PANORAMA_ID",
+	direction=["l", "f", "r"],
+	width=800,
+)
+paths = naver.save_img_face(
+	panoid="PANORAMA_ID",
+	direction=["l", "f", "r"],
+	width=800,
+)
+```
+
+Each function returns a list for face requests. `get_img()` returns one PIL
+image, while `save_img()` returns one output path.
+
+The same `save_img_face()` function can convert Naver equirectangular images by
+passing `proj_type="equirect"`. Google and Kakao use the same common
+equirectangular-to-cubemap conversion internally.
+
+`width` and `height` are optional. If either is provided, the output is always
+2:1. When both are provided, `width` takes precedence. For example,
+`width=1024, height=900` produces a `1024 x 512` image, while `height=512`
+produces a `1024 x 512` image. An odd width is rounded down to the nearest
+even width so the final image can remain exactly 2:1.
+
+When `width` is provided, the smallest available zoom that is at least as wide
+as the requested output is downloaded first, then resized to the final size.
+Without `width`, each service's default zoom is used. `zoom` is an internal
+implementation detail and is not part of the public function arguments.
+
+This package accesses public web endpoints used by each map service. Endpoint
+formats and availability may change independently of this package.
+
+Pass `save_json=True` to `save_img()` or `save_img_face()` to save the
+`get_pano_info()` result beside the image. For example, `pano.png` produces
+`pano.json`.
+
+For `save_img_face()`, the JSON `angle` is adjusted for the selected direction:
+`f` keeps the original angle, `r` adds 90 degrees, `l` subtracts 90 degrees,
+and `b` adds 180 degrees. Angles are normalized to 0-360 degrees; `u` and `d`
+keep the original horizontal angle.

streetview_tools-0.1.0/README.md

@@ -0,0 +1,90 @@
+# streetview-tools
+
+Retrieve panorama metadata and download panorama images from Google Street View,
+Naver Roadview, and Kakao Roadview.
+
+## Installation
+
+```bash
+pip install streetview-tools
+```
+
+## Usage
+
+```python
+from streetview_tools import google
+
+pano = google.get_pano_info(panoid="PANORAMA_ID")
+google.save_img(
+	panoid="PANORAMA_ID",
+	file_name="output.png",
+	width=2048,
+)
+```
+
+The same functions are available from `streetview_tools.naver` and
+`streetview_tools.kakao`.
+
+Google and Kakao also provide `save_img_face()` for saving a square direction
+crop from their equirectangular panorama images. The supported directions are
+`l`, `f`, `r`, `b`, `d`, and `u`, and the default filename is
+`PANORAMA_ID_<direction>.png`.
+
+For Naver cubic panoramas, a single direction can be saved as a square image:
+
+```python
+from streetview_tools import naver
+
+naver.save_img_face(
+	panoid="PANORAMA_ID",
+	direction="u",
+	width=800,
+)
+# PANORAMA_ID_u.png
+```
+
+Valid directions are `l`, `f`, `r`, `b`, `d`, and `u`. A direction can also be
+provided as a list, which returns or saves one image per direction:
+
+```python
+images = naver.get_img_face(
+	panoid="PANORAMA_ID",
+	direction=["l", "f", "r"],
+	width=800,
+)
+paths = naver.save_img_face(
+	panoid="PANORAMA_ID",
+	direction=["l", "f", "r"],
+	width=800,
+)
+```
+
+Each function returns a list for face requests. `get_img()` returns one PIL
+image, while `save_img()` returns one output path.
+
+The same `save_img_face()` function can convert Naver equirectangular images by
+passing `proj_type="equirect"`. Google and Kakao use the same common
+equirectangular-to-cubemap conversion internally.
+
+`width` and `height` are optional. If either is provided, the output is always
+2:1. When both are provided, `width` takes precedence. For example,
+`width=1024, height=900` produces a `1024 x 512` image, while `height=512`
+produces a `1024 x 512` image. An odd width is rounded down to the nearest
+even width so the final image can remain exactly 2:1.
+
+When `width` is provided, the smallest available zoom that is at least as wide
+as the requested output is downloaded first, then resized to the final size.
+Without `width`, each service's default zoom is used. `zoom` is an internal
+implementation detail and is not part of the public function arguments.
+
+This package accesses public web endpoints used by each map service. Endpoint
+formats and availability may change independently of this package.
+
+Pass `save_json=True` to `save_img()` or `save_img_face()` to save the
+`get_pano_info()` result beside the image. For example, `pano.png` produces
+`pano.json`.
+
+For `save_img_face()`, the JSON `angle` is adjusted for the selected direction:
+`f` keeps the original angle, `r` adds 90 degrees, `l` subtracts 90 degrees,
+and `b` adds 180 degrees. Angles are normalized to 0-360 degrees; `u` and `d`
+keep the original horizontal angle.

streetview_tools-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "streetview-tools"
+version = "0.1.0"
+description = "Retrieve street-view panorama metadata and download panorama images"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "AngLaboratory", email = "anglaboratory@gmail.com" }]
+keywords = ["streetview", "street-view", "panorama", "panoid", "roadview"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Graphics",
+    "Typing :: Typed",
+]
+dependencies = [
+    "Pillow>=9.0",
+    "numpy>=1.21",
+    "py360convert>=1.0.4",
+    "requests>=2.25",
+]
+
+[project.urls]
+Homepage = "https://github.com/AngLaboratory/streetview-tools"
+Source = "https://github.com/AngLaboratory/streetview-tools"
+Issues = "https://github.com/AngLaboratory/streetview-tools/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/streetview_tools"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

streetview_tools-0.1.0/src/streetview_tools/__init__.py

@@ -0,0 +1,4 @@
+from . import google, kakao, naver
+
+__all__ = ["google", "kakao", "naver"]
+__version__ = "0.1.0"

streetview_tools-0.1.0/src/streetview_tools/_downloader.py

@@ -0,0 +1,144 @@
+from concurrent.futures import ThreadPoolExecutor
+from copy import deepcopy
+from io import BytesIO
+import json
+from pathlib import Path
+
+import requests
+import numpy as np
+import py360convert
+from PIL import Image
+
+from ._http import REQUEST_HEADERS
+
+
+def download_tiles(
+    tile_sources,
+    output_path,
+    crop_box=None,
+    width=None,
+    height=None,
+    max_workers=8,
+):
+    canvas = download_tiles_image(tile_sources, crop_box=crop_box)
+
+    target_size = normalize_size(width, height)
+    if target_size:
+        canvas = canvas.resize(target_size, Image.Resampling.LANCZOS)
+
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    canvas.save(output_path, "PNG")
+    return output_path
+
+
+def download_tiles_image(tile_sources, crop_box=None, max_workers=8):
+    """Download and merge tiles into a PIL image without saving it."""
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        images = list(executor.map(_load_image, (item["src"] for item in tile_sources)))
+
+    canvas_width = max(item["x"] + image.width for item, image in zip(tile_sources, images))
+    canvas_height = max(item["y"] + image.height for item, image in zip(tile_sources, images))
+    canvas = Image.new("RGB", (canvas_width, canvas_height))
+
+    for item, image in zip(tile_sources, images):
+        canvas.paste(image.convert("RGB"), (item["x"], item["y"]))
+
+    if crop_box:
+        canvas = canvas.crop(tuple(crop_box))
+    return canvas
+
+
+def equirect_to_face(image, direction, face_size=None):
+    """Convert an equirectangular PIL image into one cubemap face."""
+    direction = str(direction).lower().strip()
+    if direction not in "lfrbdu" or len(direction) != 1:
+        raise ValueError("direction must be one of: l, f, r, b, d, u")
+
+    if face_size is None:
+        face_size = image.height // 2
+    if face_size <= 0:
+        raise ValueError("face_size must be positive")
+    if image.width != image.height * 2:
+        raise ValueError("equirectangular image must have a 2:1 aspect ratio")
+
+    faces = py360convert.e2c(
+        np.asarray(image.convert("RGB")),
+        face_w=face_size,
+        mode="bilinear",
+        cube_format="list",
+    )
+    face_index = {"f": 0, "r": 1, "b": 2, "l": 3, "u": 4, "d": 5}[direction]
+    return Image.fromarray(faces[face_index].astype(np.uint8), mode="RGB")
+
+
+def save_image(image, output_path):
+    """Save a PIL image and create its parent directory when needed."""
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    image.save(output_path, "PNG")
+    return output_path
+
+
+def save_pano_info_json(pano_info, image_path):
+    """Save panorama metadata beside an image using the same file stem."""
+    json_path = Path(image_path).with_suffix(".json")
+    json_path.parent.mkdir(parents=True, exist_ok=True)
+    with json_path.open("w", encoding="utf-8") as file:
+        json.dump(pano_info, file, ensure_ascii=False, indent=2)
+    return json_path
+
+
+def adjust_face_angle(pano_info, direction):
+    """Return metadata with its camera angle adjusted for a face direction."""
+    direction = str(direction).lower().strip()
+    offsets = {"f": 0, "r": 90, "b": 180, "l": -90, "u": 0, "d": 0}
+    if direction not in offsets:
+        raise ValueError("direction must be one of: l, f, r, b, d, u")
+
+    adjusted_info = deepcopy(pano_info)
+    angle = float(adjusted_info.get("angle", 0))
+    adjusted_info["angle"] = round((angle + offsets[direction]) % 360, 1)
+    return adjusted_info
+
+
+def normalize_size(width=None, height=None):
+    """Return a 2:1 output size, using width as the source of truth."""
+    if width is None and height is None:
+        return None
+
+    if width is not None:
+        width = _validate_dimension(width, "width")
+        width -= width % 2
+        width = max(2, width)
+        return width, width // 2
+
+    height = _validate_dimension(height, "height")
+    return height * 2, height
+
+
+def select_zoom(width, zoom_sizes, default_zoom):
+    """Choose the smallest zoom whose source width meets ``width``."""
+    if width is None:
+        return default_zoom
+
+    target_width = _validate_dimension(width, "width")
+    for zoom, source_width in sorted(zoom_sizes.items()):
+        if source_width >= target_width:
+            return zoom
+    return max(zoom_sizes)
+
+
+def _validate_dimension(value, name):
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ValueError(f"{name} must be a positive integer")
+    return value
+
+
+def _load_image(url):
+    response = requests.get(url, headers=REQUEST_HEADERS, timeout=10)
+    response.raise_for_status()
+    if not response.headers.get("Content-Type", "").startswith("image/"):
+        raise ValueError(f"Response is not an image: {url}")
+    with Image.open(BytesIO(response.content)) as image:
+        return image.copy()

streetview_tools-0.1.0/src/streetview_tools/_geometry.py

@@ -0,0 +1,48 @@
+import math
+
+
+def add_spot_info(base_pano):
+    base_lat = base_pano["lat"]
+    base_lon = base_pano["lon"]
+    base_angle = float(base_pano.get("angle", 0))
+    spots = []
+
+    for spot in base_pano.get("spot", []):
+        bearing = calc_bearing(base_lat, base_lon, spot["lat"], spot["lon"])
+        is_front = resolve_position(base_angle, bearing)
+        spots.append({
+            **spot,
+            "distance_m": calc_distance_meter(
+                base_lat, base_lon, spot["lat"], spot["lon"]
+            ),
+            "isFrontTF": is_front,
+            "position": "front" if is_front else "back",
+        })
+
+    base_pano["spot"] = spots
+    return base_pano
+
+
+def calc_distance_meter(lat1, lon1, lat2, lon2):
+    radius = 6371000
+    lat1, lat2 = math.radians(lat1), math.radians(lat2)
+    dlat = lat2 - lat1
+    dlon = math.radians(lon2 - lon1)
+    value = (
+        math.sin(dlat / 2) ** 2
+        + math.cos(lat1) * math.cos(lat2) * math.sin(dlon / 2) ** 2
+    )
+    return round(2 * radius * math.asin(math.sqrt(value)), 4)
+
+
+def calc_bearing(lat1, lon1, lat2, lon2):
+    lat1, lat2 = math.radians(lat1), math.radians(lat2)
+    dlon = math.radians(lon2 - lon1)
+    x = math.sin(dlon) * math.cos(lat2)
+    y = math.cos(lat1) * math.sin(lat2) - math.sin(lat1) * math.cos(lat2) * math.cos(dlon)
+    return round((math.degrees(math.atan2(x, y)) + 360) % 360, 4)
+
+
+def resolve_position(base_angle, target_bearing):
+    difference = (target_bearing - base_angle + 180) % 360 - 180
+    return -90 <= difference <= 90

streetview_tools-0.1.0/src/streetview_tools/_http.py

@@ -0,0 +1,10 @@
+REQUEST_HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) "
+        "Chrome/153.0.0.0 Safari/537.36"
+    ),
+    "Accept": "*/*",
+    "Accept-Language": "ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7",
+    "Referer": "https://www.google.com/",
+}

streetview_tools-0.1.0/src/streetview_tools/google.py

@@ -0,0 +1,245 @@
+import json
+from pathlib import Path
+from urllib.parse import quote
+
+import requests
+
+from ._downloader import (
+    download_tiles_image,
+    equirect_to_face,
+    adjust_face_angle,
+    save_image,
+    save_pano_info_json,
+    normalize_size,
+    select_zoom,
+)
+from ._geometry import add_spot_info
+from ._http import REQUEST_HEADERS
+
+_CACHE = {}
+_IMG_BLOCK_SIZE = 512
+_FACE_DIRECTIONS = "lfrbdu"
+
+
+def get_pano_info(panoid, *, spot=False):
+    """Return Google Street View metadata for ``panoid``.
+
+    Args:
+        panoid: Google panorama identifier.
+        spot: Include nearby panorama information when ``True``.
+    """
+    panoid = str(panoid).strip()
+    if not panoid:
+        raise ValueError("panoid must not be empty")
+
+    if panoid in _CACHE and (not spot or _CACHE[panoid].get("spot")):
+        return _CACHE[panoid]
+
+    response = requests.get(
+        _get_url(panoid, spot=spot),
+        headers=REQUEST_HEADERS,
+        timeout=10,
+    )
+
+    response.raise_for_status()
+
+    panorama = _parse_response(response.text, panoid=panoid)
+    _CACHE[panoid] = panorama
+    return panorama
+
+def get_img(
+    panoid,
+    *,
+    width=None,
+    height=None,
+):
+    """Return a Google equirectangular panorama as a PIL image.
+
+    ``width`` selects the smallest source zoom that is at least as wide as
+    requested, then the image is resized to the requested 2:1 dimensions.
+    When ``width`` is omitted, Google's default zoom is used.
+    """
+    panoid = str(panoid).strip()
+    zoom_seed = get_pano_info(panoid)["others"]["zoom_seed"]
+
+    zoom = select_zoom(
+        width,
+        {level: zoom_seed * (2 ** level) * 2 for level in range(6)},
+        default_zoom=3,
+    )
+
+    y_size = zoom_seed * (2 ** zoom)
+    x_size = y_size * 2
+    tiles = [
+        {"x": x * _IMG_BLOCK_SIZE, "y": y * _IMG_BLOCK_SIZE,
+         "src": _tile_url(panoid, zoom, x, y)}
+        for y in range((y_size + _IMG_BLOCK_SIZE - 1) // _IMG_BLOCK_SIZE)
+        for x in range((x_size + _IMG_BLOCK_SIZE - 1) // _IMG_BLOCK_SIZE)
+    ]
+    image = download_tiles_image(tiles, crop_box=[0, 0, x_size, y_size])
+    target_size = normalize_size(width, height)
+    if target_size:
+        image = image.resize(target_size)
+    return image
+
+
+def save_img(
+    panoid,
+    *,
+    file_name=None,
+    width=None,
+    height=None,
+    save_json=False,
+):
+    """Download and save a Google panorama PNG, optionally with JSON metadata."""
+    panoid = str(panoid).strip()
+    image = get_img(
+        panoid,
+        width=width,
+        height=height,
+    )
+    output_path = save_image(image, file_name or f"{panoid}.png")
+    if save_json:
+        save_pano_info_json(get_pano_info(panoid), output_path)
+    return output_path
+
+
+def get_img_face(
+    panoid,
+    direction,
+    *,
+    width=None,
+):
+    """Return square Google panorama faces as PIL images.
+
+    ``direction`` may be one direction or a sequence of ``l``, ``f``, ``r``,
+    ``b``, ``d``, and ``u``. ``width`` selects the smallest face source zoom
+    at least that wide; omitted width uses Google's default zoom.
+    """
+    panoid = str(panoid).strip()
+    directions = _normalize_directions(direction)
+    zoom_seed = get_pano_info(panoid)["others"]["zoom_seed"]
+
+    zoom = select_zoom(
+        width,
+        {level: zoom_seed * (2 ** level) // 2 for level in range(6)},
+        default_zoom=3,
+    )
+
+    panorama_height = zoom_seed * (2 ** zoom)
+    panorama_width = panorama_height * 2
+    tiles = [
+        {"x": x * _IMG_BLOCK_SIZE, "y": y * _IMG_BLOCK_SIZE,
+         "src": _tile_url(panoid, zoom, x, y)}
+        for y in range((panorama_height + _IMG_BLOCK_SIZE - 1) // _IMG_BLOCK_SIZE)
+        for x in range((panorama_width + _IMG_BLOCK_SIZE - 1) // _IMG_BLOCK_SIZE)
+    ]
+    panorama = download_tiles_image(tiles, crop_box=[0, 0, panorama_width, panorama_height])
+
+    images = [equirect_to_face(panorama, item) for item in directions]
+    if width is not None:
+        target_size = normalize_size(width)[0]
+        images = [image.resize((target_size, target_size)) for image in images]
+    return images
+
+
+def save_img_face(
+    panoid,
+    direction,
+    *,
+    file_name=None,
+    width=None,
+    save_json=False,
+):
+    """Download and save square Google panorama face PNG files."""
+    directions = _normalize_directions(direction)
+    images = get_img_face(
+        panoid, directions, width=width
+    )
+    pano_info = get_pano_info(panoid) if save_json else None
+    output_paths = []
+    for item, image in zip(directions, images):
+        output_path = save_image(
+            image, _face_file_name(panoid, item, file_name, len(directions))
+        )
+        if pano_info is not None:
+            save_pano_info_json(adjust_face_angle(pano_info, item), output_path)
+        output_paths.append(output_path)
+    return output_paths
+
+
+def _normalize_directions(direction):
+    directions = [direction] if isinstance(direction, str) else list(direction)
+    directions = [str(item).lower().strip() for item in directions]
+    if not directions or any(item not in _FACE_DIRECTIONS for item in directions):
+        raise ValueError("direction must contain only: l, f, r, b, d, u")
+    return directions
+
+
+def _face_file_name(panoid, direction, file_name, count):
+    if not file_name:
+        return f"{panoid}_{direction}.png"
+    if count == 1:
+        return file_name
+    path = Path(file_name)
+    return path.with_name(f"{path.stem}_{direction}{path.suffix or '.png'}")
+
+
+def _get_url(panoid, *, spot):
+    spot_call = "!1e6" if spot else "!1e1"
+    e_code = "10" if len(panoid) in (43, 44) else "2"
+    
+    return (
+        "https://www.google.com/maps/photometa/v1?authuser=0&hl=en&gl=us&pb="
+        "!1m4!1smaps_sv.tactile!11m2!2m1!1b1!2m2!1sen!2sus"
+        f"!3m3!1m2!1e{e_code}!2s{quote(panoid)}"
+        f"!4m57!1e1!1e2!1e4!1e1!1e1!1e1!1e1{spot_call}"
+        "!2m1!1e1!4m1!1i48!5m1!1e1!5m1!1e2!6m1!1e1!6m1!1e2"
+        "!9m36!1m3!1e6!2b0!3e0!1m3!1e6!2b0!3e1!1m3!1e6!2b0!3e2"
+        "!1m3!1e6!2b0!3e3!1m3!1e6!2b0!3e4!1m3!1e6!2b0!3e5"
+        "!1m3!1e6!2b0!3e6!1m3!1e6!2b0!3e7!1m3!1e6!2b0!3e8"
+    )
+
+
+def _parse_response(text, panoid=""):
+    try:
+        parsed = json.loads(text[5:])
+        data = parsed[1][0]
+    except (json.JSONDecodeError, IndexError, TypeError):
+        raise ValueError(f"Invalid response from Google Street View for '{panoid}'")
+
+    if not data or len(data) < 6 or data[2] is None or data[5] is None:
+        target_id = panoid or (data[1][1] if len(data) > 1 and len(data[1]) > 1 else "unknown")
+        raise ValueError(f"Google Street View panorama not found or unavailable: '{target_id}'")
+
+    addresses = data[3][2] if data[3] is not None and len(data[3]) > 2 else []
+    date_str = ""
+    if len(data) > 6 and data[6] and len(data[6]) > 7 and data[6][7]:
+        date_str = f"{data[6][7][0]}-{data[6][7][1]:02d}-01"
+
+    panorama = {
+        "id": data[1][1],
+        "date": date_str,
+        "lon": float(data[5][0][1][0][3]),
+        "lat": float(data[5][0][1][0][2]),
+        "angle": round(float(data[5][0][1][2][0]), 1),
+        "addr1": addresses[1][0] if len(addresses) > 1 else (addresses[0][0] if addresses else ""),
+        "addr2": addresses[0][0] if len(addresses) > 1 else "",
+        "others": {"zoom_seed": data[2][3][0][0][0][0]},
+        "spot": [],
+    }
+    if len(data[5][0]) > 3 and data[5][0][3]:
+        for item in data[5][0][3][0]:
+            if len(item) >= 3 and item[0][1] != panorama["id"] and item[2] is not None:
+                panorama["spot"].append({
+                    "id": item[0][1],
+                    "lon": item[2][0][3],
+                    "lat": item[2][0][2],
+                    "x": item[2][0][3],
+                    "y": item[2][0][2],
+                })
+    return add_spot_info(panorama)
+
+
+def _tile_url(panoid, zoom, x, y):
+    return f"https://streetviewpixels-pa.googleapis.com/v1/tile?cb_client=maps_sv.tactile&zoom={zoom}&panoid={panoid}&x={x}&y={y}"

streetview_tools-0.1.0/src/streetview_tools/kakao.py

@@ -0,0 +1,166 @@
+from pathlib import Path
+
+import requests
+
+from ._downloader import (
+    download_tiles_image,
+    equirect_to_face,
+    adjust_face_angle,
+    save_image,
+    save_pano_info_json,
+    normalize_size,
+    select_zoom,
+)
+from ._geometry import add_spot_info
+from ._http import REQUEST_HEADERS
+
+_CACHE = {}
+_FACE_DIRECTIONS = "lfrbdu"
+
+
+def get_pano_info(panoid, *, spot=False):
+    """Return Kakao Roadview metadata for ``panoid``.
+
+    Args:
+        panoid: Kakao panorama identifier.
+        spot: Include nearby panorama information when ``True``.
+    """
+    panoid = str(panoid).strip()
+    if not panoid:
+        raise ValueError("panoid must not be empty")
+    if panoid in _CACHE and (not spot or _CACHE[panoid].get("spot")):
+        return _CACHE[panoid]
+
+    response = requests.get(
+        f"https://rv.map.kakao.com/roadview-search/v2/node/{panoid}",
+        headers=REQUEST_HEADERS,
+        timeout=10,
+    )
+    response.raise_for_status()
+    data = response.json()["street_view"]["street"]
+    panorama = {
+        "id": data["id"], "date": data["shot_date"],
+        "lon": float(data["wgsx"]), "lat": float(data["wgsy"]),
+        "angle": float(data["angle"]), "addr1": data["addr"],
+        "addr2": data["st_name"], "others": {"img_path": data["img_path"]}, "spot": [],
+    }
+    for spot in data.get("spot", []):
+        if spot["id"] != panorama["id"]:
+            panorama["spot"].append({"id": spot["id"], "lon": spot["wgsx"], "lat": spot["wgsy"]})
+    panorama = add_spot_info(panorama)
+    _CACHE[panoid] = panorama
+    return panorama
+
+
+def get_img(
+    panoid,
+    *,
+    width=None,
+    height=None,
+):
+    """Return a Kakao Roadview panorama as a PIL image.
+
+    ``width`` selects the smallest source zoom at least as wide as requested;
+    without it, Kakao's default zoom is used.
+    """
+    panorama = get_pano_info(panoid)
+    zoom = select_zoom(
+        width,
+        {0: 1280, 1: 4096},
+        default_zoom=1,
+    )
+    image_path = panorama["others"]["img_path"]
+    if zoom == 0:
+        tiles = [{"x": 0, "y": 0, "src": f"https://map.kakaocdn.net/map_roadview{image_path}.jpg"}]
+        crop_box = [0, 0, 1280, 640]
+    else:
+        tiles = [{"x": x * 512, "y": y * 512,
+                  "src": _tile_url(image_path, tile_number)}
+                 for tile_number, (y, x) in enumerate(
+                     ((y, x) for y in range(4) for x in range(8)), 1
+                 )]
+        crop_box = [0, 0, 4096, 2048]
+    image = download_tiles_image(
+        tiles,
+        crop_box,
+    )
+    target_size = normalize_size(width, height)
+    if target_size:
+        image = image.resize(target_size)
+    return image
+
+
+def save_img(
+    panoid,
+    *,
+    file_name=None,
+    width=None,
+    height=None,
+    save_json=False,
+):
+    """Download and save a Kakao panorama PNG, optionally with JSON metadata."""
+    image = get_img(panoid, width=width, height=height)
+    output_path = save_image(image, file_name or f"{panoid}.png")
+    if save_json:
+        save_pano_info_json(get_pano_info(panoid), output_path)
+    return output_path
+
+
+def get_img_face(panoid, direction, *, width=None):
+    """Return Kakao panorama direction faces as PIL images.
+
+    ``direction`` may be one direction or a sequence of ``l``, ``f``, ``r``,
+    ``b``, ``d``, and ``u``. ``width`` controls the final square face size.
+    """
+    panoid = str(panoid).strip()
+    directions = [direction] if isinstance(direction, str) else list(direction)
+    directions = [str(item).lower().strip() for item in directions]
+    if not directions or any(item not in _FACE_DIRECTIONS for item in directions):
+        raise ValueError("direction must contain only: l, f, r, b, d, u")
+    panorama_width, panorama_height = 4096, 2048
+    face_size = panorama_width // 4
+    image_path = get_pano_info(panoid)["others"]["img_path"]
+
+    tiles = [
+        {"x": x * 512, "y": y * 512,
+         "src": _tile_url(image_path, tile_number)}
+        for tile_number, (y, x) in enumerate(
+            ((y, x) for y in range(4) for x in range(8)), 1
+        )
+    ]
+
+    panorama_image = download_tiles_image(tiles)
+    images = [
+        equirect_to_face(panorama_image, item, face_size=face_size)
+        for item in directions
+    ]
+    if width is not None:
+        images = [image.resize((width, width)) for image in images]
+    return images
+
+
+def save_img_face(panoid, direction, *, file_name=None, width=None, save_json=False):
+    """Download and save Kakao panorama face PNG files."""
+    directions = [direction] if isinstance(direction, str) else list(direction)
+    directions = [str(item).lower().strip() for item in directions]
+    images = get_img_face(panoid, directions, width=width)
+    pano_info = get_pano_info(panoid) if save_json else None
+    output_paths = []
+    for item, image in zip(directions, images):
+        if file_name and len(directions) == 1:
+            output_name = file_name
+        elif file_name:
+            path = Path(file_name)
+            output_name = path.with_name(f"{path.stem}_{item}{path.suffix or '.png'}")
+        else:
+            output_name = f"{panoid}_{item}.png"
+        output_path = save_image(image, output_name)
+        if pano_info is not None:
+            save_pano_info_json(adjust_face_angle(pano_info, item), output_path)
+        output_paths.append(output_path)
+    return output_paths
+
+
+def _tile_url(image_path, tile_number):
+    suffix = image_path[image_path.rfind("/"):]
+    return f"https://map.kakaocdn.net/map_roadview{image_path}{suffix}_{tile_number:02d}.jpg"

streetview_tools-0.1.0/src/streetview_tools/naver.py

@@ -0,0 +1,223 @@
+from pathlib import Path
+
+import requests
+
+from ._downloader import (
+    download_tiles_image,
+    equirect_to_face,
+    adjust_face_angle,
+    save_image,
+    save_pano_info_json,
+    normalize_size,
+    select_zoom,
+)
+from ._geometry import add_spot_info
+from ._http import REQUEST_HEADERS
+
+_CACHE = {}
+
+
+def get_pano_info(panoid, *, spot=False):
+    """Return Naver Roadview metadata for ``panoid``.
+
+    Args:
+        panoid: Naver panorama identifier.
+        spot: Include nearby panorama information when ``True``.
+    """
+    panoid = str(panoid).strip()
+    if not panoid:
+        raise ValueError("panoid must not be empty")
+    if panoid in _CACHE and (not spot or _CACHE[panoid].get("spot")):
+        return _CACHE[panoid]
+
+    response = requests.get(
+        f"https://panorama.map.naver.com/metadataV3/basic/{panoid}?lang=ko",
+        headers=REQUEST_HEADERS,
+        timeout=10,
+    )
+    response.raise_for_status()
+    data = response.json()
+    panorama = {
+        "id": data["id"], "date": data["info"]["photodate"],
+        "lon": float(data["longitude"]), "lat": float(data["latitude"]),
+        "angle": float(data["camera_angle"][1]),
+        "addr1": data["info"]["description"], "addr2": data["info"]["title"],
+        "others": {"proj_type": data["proj_type"]}, "spot": [],
+    }
+    for link in data.get("links", []):
+        if link["id"] != panorama["id"]:
+            panorama["spot"].append({"id": link["id"], "lon": link["longitude"], "lat": link["latitude"]})
+    panorama = add_spot_info(panorama)
+    _CACHE[panoid] = panorama
+    return panorama
+
+
+def get_img(
+    panoid,
+    *,
+    proj_type="cubic",
+    width=None,
+    height=None,
+):
+    """Return a Naver panorama as a PIL image.
+
+    ``width`` selects the smallest available source zoom at least as wide as
+    requested. When omitted, the default zoom for the selected projection is
+    used.
+    """
+    panoid = str(panoid).strip()
+    pano_info = None
+    if proj_type == "equirect":
+        pano_info = get_pano_info(panoid)
+        if pano_info["others"]["proj_type"] != "equirect":
+            raise ValueError("This panorama does not support equirect projection")
+        zoom = select_zoom(
+            width,
+            {0: 1024, 1: 2048, 2: 4096, 3: 8192},
+            default_zoom=2,
+        )
+        if zoom == 0:
+            tiles = [{"x": 0, "y": 0, "src": _equirect_url(panoid, zoom, None, None)}]
+        else:
+            tiles = [{"x": x * 512, "y": y * 512, "src": _equirect_url(panoid, zoom, x, y)}
+                     for y in range(2 ** zoom) for x in range(2 ** (zoom + 1))]
+        size = (1024 * 2 ** zoom, 512 * 2 ** zoom)
+    else:
+        zoom = select_zoom(
+            width,
+            {0: 1536, 1: 6144},
+            default_zoom=1,
+        )
+        if zoom == 0:
+            tiles, size = [{"x": 0, "y": 0, "src": _cubic_url(panoid, zoom, None, None, None)}], (1536, 256)
+        else:
+            faces = "lfrbdu"
+            tiles = [{"x": x * 512 + face_index * 1024, "y": y * 512,
+                      "src": _cubic_url(panoid, zoom, face, x, y)}
+                     for face_index, face in enumerate(faces) for y in range(2) for x in range(2)]
+            size = (6144, 1024)
+    image = download_tiles_image(
+        tiles,
+        [0, 0, *size],
+    )
+    target_size = normalize_size(width, height)
+    if target_size:
+        image = image.resize(target_size)
+    return image
+
+
+def save_img(
+    panoid,
+    *,
+    file_name=None,
+    proj_type="cubic",
+    width=None,
+    height=None,
+    save_json=False,
+):
+    """Download and save a Naver panorama PNG, optionally with JSON metadata."""
+    image = get_img(
+        panoid, proj_type=proj_type, width=width, height=height
+    )
+    output_path = save_image(image, file_name or f"{panoid}.png")
+    if save_json:
+        save_pano_info_json(get_pano_info(panoid), output_path)
+    return output_path
+
+
+def get_img_face(
+    panoid,
+    direction,
+    *,
+    proj_type="cubic",
+    width=None,
+):
+    """Return Naver panorama direction faces as PIL images.
+
+    ``direction`` must be one of ``l``, ``f``, ``r``, ``b``, ``d``, or ``u``.
+    Cubic panoramas use their direction-specific tiles; equirectangular
+    panoramas are converted to a cubemap face with the common converter.
+    """
+    panoid = str(panoid).strip()
+    directions = [direction] if isinstance(direction, str) else list(direction)
+    directions = [str(item).lower().strip() for item in directions]
+    if not directions or any(item not in "lfrbdu" for item in directions):
+        raise ValueError("direction must contain only: l, f, r, b, d, u")
+
+    if proj_type == "equirect":
+        pano_info = get_pano_info(panoid)
+        if pano_info["others"]["proj_type"] != "equirect":
+            raise ValueError("This panorama does not support equirect projection")
+        zoom = select_zoom(width, {level: 512 * 2 ** level for level in range(4)}, 2)
+        tiles = (
+            [{"x": 0, "y": 0, "src": _equirect_url(panoid, zoom, None, None)}]
+            if zoom == 0
+            else [
+                {"x": x * 512, "y": y * 512,
+                 "src": _equirect_url(panoid, zoom, x, y)}
+                for y in range(2 ** zoom)
+                for x in range(2 ** (zoom + 1))
+            ]
+        )
+        panorama = download_tiles_image(tiles)
+        images = [
+            equirect_to_face(panorama, item, face_size=panorama.height // 2)
+            for item in directions
+        ]
+        if width is not None:
+            images = [image.resize((width, width)) for image in images]
+        return images
+
+    zoom = 1
+    images = []
+    for item in directions:
+        tiles = [
+            {"x": x * 512, "y": y * 512, "src": _cubic_url(panoid, zoom, item, x, y)}
+            for y in range(2)
+            for x in range(2)
+        ]
+        image = download_tiles_image(tiles, crop_box=[0, 0, 1024, 1024])
+        images.append(image.resize((width, width)) if width else image)
+    return images
+
+
+def save_img_face(
+    panoid,
+    direction,
+    *,
+    file_name=None,
+    proj_type="cubic",
+    width=None,
+    save_json=False,
+):
+    """Download and save Naver panorama face PNG files."""
+    directions = [direction] if isinstance(direction, str) else list(direction)
+    directions = [str(item).lower().strip() for item in directions]
+    images = get_img_face(panoid, directions, proj_type=proj_type, width=width)
+    pano_info = get_pano_info(panoid) if save_json else None
+    output_paths = []
+    for item, image in zip(directions, images):
+        if file_name and len(directions) == 1:
+            output_name = file_name
+        elif file_name:
+            path = Path(file_name)
+            output_name = path.with_name(f"{path.stem}_{item}{path.suffix or '.png'}")
+        else:
+            output_name = f"{panoid}_{item}.png"
+        output_path = save_image(image, output_name)
+        if pano_info is not None:
+            save_pano_info_json(adjust_face_angle(pano_info, item), output_path)
+        output_paths.append(output_path)
+    return output_paths
+
+
+def _equirect_url(panoid, zoom, x, y):
+    if zoom == 0:
+        return f"https://panorama.pstatic.net/imageV3/{panoid}/P"
+    return f"https://panorama.pstatic.net/imageV3/{panoid}/{zoom - 1}/{x + 1}/{y + 1}"
+
+
+def _cubic_url(panoid, zoom, face, x, y):
+    if zoom == 0:
+        return f"https://panorama.pstatic.net/image/{panoid}/512/P"
+    return f"https://panorama.pstatic.net/image/{panoid}/512/M/{face}/{x + 1}/{y + 1}"