:py:mod:`panorama`
==================

.. py:module:: panorama

.. autoapi-nested-parse::

   This module allows panorama images to be downloaded by their
   internal panorama IDs. Each panorama ID is a string of 22
   alphanumeric characters alongside - and _, found in Google
   Street View URLs after '1s'. The user is responsible for obtaining
   the panorama IDs for the panoramas they wish to download.

   Here is an example of a URL and its corresponding panorama ID:
   https://www.google.co.uk/maps/@51.5002793,-0.1490781,3a,75y,169.86h,65.89t/data=!3m6!1e1!3m4!1sL3GLvqpla79_pSq2fxUunw!2e0!7i16384!8i8192?entry=ttu

   Panorama ID: L3GLvqpla79_pSq2fxUunw

   Zooming in/out is supported, where there are 6 levels of zoom
   from 0 to 5, with increased resolution for each level.

   Partial panorama downloading is also possible, since panoramas
   are split into square tiles, and as zoom increases, the number
   of tiles increases, so a subset of tiles can be downloaded accordingly.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   panorama.PanoramaSettings



Functions
~~~~~~~~~

.. autoapisummary::

   panorama.get_max_coordinates
   panorama.get_panorama
   panorama.get_pil_panorama
   panorama.get_pil_tiles
   panorama.get_tiles
   panorama.validate_panorama_id



Attributes
~~~~~~~~~~

.. autoapisummary::

   panorama.MAX_ZOOM
   panorama.MIN_ZOOM
   panorama.PANORAMA_ID_LENGTH


.. py:data:: MAX_ZOOM
   :value: 5

   

.. py:data:: MIN_ZOOM
   :value: 0

   

.. py:data:: PANORAMA_ID_LENGTH
   :value: 22

   

.. py:class:: PanoramaSettings(zoom: int = 0, top_left: tuple[int, int] = None, bottom_right: tuple[int, int] = None)


   Stores panorama download settings, including the level of zoom
   and the top left and bottom right coordinates. By default, zoom
   is 0 (minimum), and the entire panorama is downloaded.

   .. py:property:: bottom_right
      :type: tuple[int, int]

      Bottom-right coordinates (x, y)


   .. py:property:: height
      :type: int

      Height of the tiles covered by the settings (number of tiles down).


   .. py:property:: tiles
      :type: int

      Total number of tiles covered by the current settings.
      Equivalent to the product of the width and height in tiles.


   .. py:property:: top_left
      :type: tuple[int, int]

      Top-left coordinates (x, y)


   .. py:property:: width
      :type: int

      Width of the tiles covered by the settings (number of tiles across).


   .. py:property:: zoom
      :type: int

      Current zoom level, between 0 and 5.


   .. py:method:: update(zoom: int, top_left: tuple[int, int], bottom_right: tuple[int, int]) -> None

      Sets/updates the settings.



.. py:function:: get_max_coordinates(zoom: int) -> tuple[int, int]

   Returns the maximum (bottom right) tile coordinates for a given zoom.
   If the return coordinate is (x, y), x is the number of columns
   and y is the number of rows.

   Max coordinates by zoom:

   0 - (1, 1) - 1 tile

   1 - (2, 1) - 2 tiles

   2 - (4, 2) - 8 tiles

   3 - (8, 4) - 32 tiles

   4 - (16, 8) - 128 tiles

   5 - (32, 16) - 512 tiles


.. py:function:: get_panorama(panorama_id: str, settings: PanoramaSettings = None, use_async: bool = True, crop_black_edges=True) -> bytes

   Downloads all required tiles of a panorama, and then merges the tiles
   together, returning the resulting JPEG image in bytes.
   For more information, see the `get_pil_panorama` documentation.


.. py:function:: get_pil_panorama(panorama_id: str, settings: PanoramaSettings = None, use_async: bool = True, crop_black_edges: bool = True) -> PIL.Image.Image

   Downloads all required tiles of a panorama,
   and then merges the tiles together, returning a single PIL Image.
   Default panorama settings are used if not supplied.
   By default, asynchronous processing is used, otherwise serial
   requests are performed if `use_async` is set to False.
   Many panoramas have entirely black rows and columns at the
   bottom and on the right, which are stripped away provided
   `crop_black_edges` is set to True.


.. py:function:: get_pil_tiles(panorama_id: str, settings: PanoramaSettings = None, use_async: bool = True) -> list[list[PIL.Image.Image]]

   Returns a 2D list of PIL images representing each downloaded tile.
   See the `get_tiles` documentation for more information.


.. py:function:: get_tiles(panorama_id: str, settings: PanoramaSettings = None, use_async: bool = True) -> list[list[bytes]]

   Returns a 2D list of JPEG images in bytes, where each element is
   one tile at one (x, y) coordinate, as defined in the panorama settings.
   If `settings` are not provided, use the default settings.
   If `use_async` is set to True, then speed up image downloads using
   asynchronous processing. Otherwise, use serial requests.


.. py:function:: validate_panorama_id(panorama_id: str) -> None

   Performs validation on a panorama ID.
   The panorama ID must be a 22 character string consisting
   of letters, numbers, and dashes/underscores only.
   Note: the existence of valid panorama IDs is not checked.