Async Raster

The async Raster module provides functionality for working with rasters.

class AsyncRaster(api, uuid, data={})[source]

Bases: AsyncBase

Parameters:
BASE_ENDPOINT: str = 'rasters/'
__init__(api, uuid, data={})[source]

Constructs all the necessary attributes for the Raster object.

Parameters:

  • api (AsyncGeoboxClient) – The API instance.

  • uuid (str) – The UUID of the raster.

  • data (Dict, optional) – The raster data.

async classmethod get_rasters(api, **kwargs)[source]

[async] Get all rasters.

Parameters:

api (AsyncGeoboxClient) – The API instance.

Keyword Arguments:

  • terrain (bool) – whether to get terrain rasters.

  • q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

  • search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

  • search_fields (str) – comma separated list of fields for searching

  • order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

  • return_count (bool) – whether to return the total count of rasters. default is False.

  • skip (int) – number of rasters to skip. minimum is 0.

  • limit (int) – number of rasters to return. minimum is 1.

  • user_id (int) – user id to show the rasters of the user. privileges required.

  • shared (bool) – whether to return shared rasters. default is False.

Returns:

A list of Raster objects or the total count of rasters.

Return type:

List[AsyncRaster] | int

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     rasters = await AsyncRaster.get_rasters(client, terrain=True, q="name LIKE '%GIS%'")
or
>>>     rasters = await client.get_rasters(terrain=True, q="name LIKE '%GIS%'")
async classmethod get_rasters_by_ids(api, ids, user_id=None)[source]

[async] Get rasters by their IDs.

Parameters:

  • api (AsyncGeoboxClient) – The API instance.

  • ids (List[str]) – The IDs of the rasters.

  • user_id (int, optional) – specific user. privileges required.

Returns:

A list of Raster objects.

Return type:

List[‘AsyncRaster’]

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     rasters = await AsyncRaster.get_rasters_by_ids(client, ids=['123', '456'])
or
>>>     rasters = await client.get_rasters_by_ids(ids=['123', '456'])
async classmethod get_raster(api, uuid, user_id=None)[source]

[async] Get a raster by its UUID.

Parameters:

  • api (AsyncGeoboxClient) – The API instance.

  • uuid (str) – The UUID of the raster.

  • user_id (int, optional) – specific user. privileges required.

Returns:

A Raster object.

Return type:

AsyncRaster

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
or
>>>     raster = await client.get_raster(uuid="12345678-1234-5678-1234-567812345678")
async classmethod get_raster_by_name(api, name, user_id=None)[source]

[async] Get a raster by name

Parameters:

  • api (AsyncGeoboxClient) – The AsyncGeoboxClient instance for making requests.

  • name (str) – the name of the raster to get

  • user_id (int, optional) – specific user. privileges required.

Returns:

returns the raster if a raster matches the given name, else None

Return type:

AsyncRaster | None

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster_by_name(client, name='test')
or
>>>     raster = await client.get_raster_by_name(name='test')
async update(**kwargs)[source]

[async] Update the raster.

Keyword Arguments:

  • name (str) – The name of the raster.

  • display_name (str) – The display name of the raster.

  • description (str) – The description of the raster.

Returns:

None

Return type:

None

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await raster.update(name="new_name")
async delete()[source]

[async] Delete the raster.

Returns:

None

Return type:

None

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await raster.delete()
property thumbnail: str

Get the thumbnail of the raster.

Returns:

The url of the thumbnail.

Return type:

str

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     raster.thumbnail
property info: Dict

[async] Get the info of the raster.

Returns:

The info of the raster.

Return type:

Dict

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await raster.info
async get_statistics(indexes=None)[source]

[async] Get the statistics of the raster.

Parameters:

indexes (str) – list of comma separated band indexes. e.g. 1, 2, 3

Returns:

The statistics of the raster.

Return type:

Dict

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await raster.get_statistics(indexes='1, 2, 3')
async get_point(lat, lng)[source]

[async] Get the point of the raster.

Parameters:

  • lat (float) – The latitude of the point. minimum is -90, maximum is 90.

  • lng (float) – The longitude of the point. minimum is -180, maximum is 180.

Returns:

The point of the raster.

Return type:

Dict

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await raster.get_point(lat=60, lng=50)
_get_save_path(save_path=None)[source]

Get the path where the file should be saved.

Parameters:

save_path (str, optional) – The path to save the file.

Returns:

The path where the file is saved.

Return type:

str

Raises:

ValueError – If save_path does not end with a ‘/’.

_get_file_name(response)[source]

Get the file name from the response.

Parameters:

response (requests.Response) – The response of the request.

Returns:

The file name

Return type:

str

_create_progress_bar()[source]

Creates a progress bar for the task.

Return type:

tqdm

async download(save_path=None, progress_bar=True)[source]

[async] Download the raster.

Parameters:

  • save_path (str, optional) – Path where the file should be saved. If not provided, it saves to the current working directory using the original filename and appropriate extension.

  • progress_bar (bool, optional) – Whether to show a progress bar. default: True

Returns:

The path to save the raster.

Return type:

str

Raises:

  • ValueError – If file_uuid is not set

  • OSError – If there are issues with file operations

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await raster.download(save_path="path/to/save/")
async get_content_file(save_path=None, progress_bar=True)[source]

[async] Get Raster Content URL

Parameters:

  • save_path (str, optional) – Path where the file should be saved. If not provided, it saves to the current working directory using the original filename and appropriate extension.

  • progress_bar (bool, optional) – Whether to show a progress bar. default: True

Returns:

The path to save the raster.

Return type:

str

Raises:

  • ValueError – If uuid is not set

  • OSError – If there are issues with file operations

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     raster_tiff = await raste.get_content_file()
get_render_png_url(x, y, z, **kwargs)[source]

Get the PNG URL of the raster.

Parameters:

  • x (int) – The x coordinate of the tile.

  • y (int) – The y coordinate of the tile.

  • z (int) – The zoom level of the tile.

Keyword Arguments:

  • indexes (str, optional) – list of comma separated band indexes to be rendered. e.g. 1, 2, 3

  • nodata (int, optional)

  • expression (str, optional) – band math expression. e.g. b1*b2+b3

  • rescale (List, optional) – comma (‘,’) separated Min,Max range. Can set multiple time for multiple bands.

  • color_formula (str, optional) – Color formula. e.g. gamma R 0.5

  • colormap_name (str, optional)

  • colormap (str, optional) – JSON encoded custom Colormap. e.g. {“0”: “#ff0000”, “1”: “#00ff00”} or [[[0, 100], “#ff0000”], [[100, 200], “#00ff00”]]

Returns:

The PNG Render URL of the raster.

Return type:

str

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     raster.get_tile_render_url(x=10, y=20, z=1)
get_tile_pbf_url(x='{x}', y='{y}', z='{z}', indexes=None)[source]

Get the URL of the tile.

Parameters:

  • x (int, optional) – The x coordinate of the tile.

  • y (int, optional) – The y coordinate of the tile.

  • z (int, optional) – The zoom level of the tile.

  • indexes (str, optional) – list of comma separated band indexes to be rendered. e.g. 1, 2, 3

Returns:

The URL of the tile.

Return type:

str

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     raster.get_tile_pbf_url(x=10, y=20, z=1)
get_tile_png_url(x='x', y='y', z='z')[source]

Get the URL of the tile.

Parameters:

  • x (int, optional) – The x coordinate of the tile.

  • y (int, optional) – The y coordinate of the tile.

  • z (int, optional) – The zoom level of the tile.

Returns:

The URL of the tile.

Return type:

str

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     raster.get_tile_png_url(x=10, y=20, z=1)
async get_tile_json()[source]

[async] Get the tile JSON of the raster.

Returns:

The tile JSON of the raster.

Return type:

Dict

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await raster.get_tile_json()
wmts(scale=None)[source]

Get the WMTS URL

Parameters:

scale (int, optional) – The scale of the raster. values are: 1, 2

Returns:

the raster WMTS URL

Return type:

str

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     raster.wmts(scale=1)
property settings: Dict

[async] Get the settings of the raster.

Returns:

The settings of the raster.

Return type:

Dict

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await raster.settings
async update_settings(settings)[source]

[async] Update the settings

settings (Dict): settings dictionary

Returns:

updated settings

Return type:

Dict

Parameters:

settings (Dict)

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> async with AsyncGeoboxClient() as client:
>>>     raster1 = client.get_raster(uuid="12345678-1234-5678-1234-567812345678")
>>>     raster2 = client.get_raster(uuid="12345678-1234-5678-1234-567812345678")
>>>     raster1.update_settings(raster2.settings)
async set_settings(**kwargs)[source]

[async] Set the settings of the raster.

Keyword Arguments:

  • nodata (int) – The nodata value of the raster.

  • indexes (list[int]) – The indexes of the raster.

  • rescale (list[int]) – The rescale of the raster.

  • colormap_name (str) – The colormap name of the raster.

  • color_formula (str) – The color formula of the raster.

  • expression (str) – The expression of the raster.

  • exaggeraion (int) – The exaggeraion of the raster.

  • min_zoom (int) – The min zoom of the raster.

  • max_zoom (int) – The max zoom of the raster.

  • use_cache (bool) – Whether to use cache of the raster.

  • cache_until_zoom (int) – The cache until zoom of the raster.

Return type:

None

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await raster.set_settings(nodata=0,
...                             indexes=[1],
...                             rescale=[[0, 10000]],
...                             colormap_name='gist_rainbow',
...                             color_formula='Gamma R 0.5',
...                             expression='b1 * 2',
...                             exaggeraion=10,
...                             min_zoom=0,
...                             max_zoom=22,
...                             use_cache=True,
...                             cache_until_zoom=17)
async share(users)[source]

[async] Shares the raster with specified users.

Parameters:

users (List[AsyncUser]) – The list of user objects to share the raster with.

Returns:

None

Return type:

None

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     users = await client.search_users(search="John")
>>>     await raster.share(users=users)
async unshare(users)[source]

[async] Unshares the raster with specified users.

Parameters:

users (List[AsyncUser]) – The list of user objects to unshare the raster with.

Returns:

None

Return type:

None

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     users = await client.search_users(search="John")
>>>     await raster.unshare(users=users)
async get_shared_users(search=None, skip=0, limit=10)[source]

[async] Retrieves the list of users the raster is shared with.

Parameters:

  • search (str, optional) – The search query.

  • skip (int, optional) – The number of users to skip.

  • limit (int, optional) – The maximum number of users to retrieve.

Returns:

The list of shared users.

Return type:

List[AsyncUser]

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await raster.get_shared_users(search='John', skip=0, limit=10)
async seed_cache(from_zoom=None, to_zoom=None, extent=None, workers=1)[source]

[async] Seed the cache of the raster.

Parameters:

  • from_zoom (int, optional) – The from zoom of the raster.

  • to_zoom (int, optional) – The to zoom of the raster.

  • extent (List[int], optional) – The extent of the raster.

  • workers (int, optional) – The number of workers to use. default is 1.

Returns:

The task of the seed cache.

Return type:

AsyncTask

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     task = await raster.seed_cache(from_zoom=0, to_zoom=22, extent=[0, 0, 100, 100], workers=1)
async clear_cache()[source]

[async] Clear the cache of the raster.

Returns:

None

Return type:

None

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await raster.clear_cache()
property cache_size: int

[async] Get the size of the cache of the raster.

Returns:

The size of the cache of the raster.

Return type:

int

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.raster import AsyncRaster
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await AsyncRaster.get_raster(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await raster.cache_size
async profile(polyline, number_of_samples=100, output_epsg=None, include_distance=True, treat_nodata_as_null=True)[source]

[async] Create a profile form a raster along a path

Parameters:

  • polyline (List) – Path coordinates as [x, y] pairs. Use raster CRS unless output_epsg is provided.

  • number_of_samples (int, optional) – Number of samples along the path. default: 100.

  • output_epsg (int, optional) – EPSG code for output coordinates. If None, use raster CRS.

  • include_distance (bool, optional) – Include cumulative distance for each sample. default: True.

  • treat_nodata_as_null (bool, optional) – Treat NoData pixels as null values. default: True.

Returns:

the profile result as geojson

Return type:

Dict

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> async with AsyncGeoboxClient() as client:
>>>     raster = await client.get_raster(uuid="12345678-1234-5678-1234-567812345678")
>>>     task = await raster.profile(polyline=[[0, 0], [10, 10]], number_of_samples=200)