From 2b0986fcda0fb537ee4cea60900b6f9c0797cbea Mon Sep 17 00:00:00 2001 From: "Stephen C. Pope" Date: Mon, 18 Sep 2023 10:21:01 -0700 Subject: [PATCH] Client API docs: Remove references to Scenes (#12170) GitOrigin-RevId: adcc17f5bd8fbc91c2f2a037ea5c7929896a9cb1 --- descarteslabs/core/catalog/band.py | 4 +- descarteslabs/core/catalog/image.py | 1 - .../catalog/tests/test_image_collection.py | 14 ++----- .../core/client/services/metadata/metadata.py | 8 ++-- .../core/client/services/raster/raster.py | 42 +++---------------- descarteslabs/core/common/display/_display.py | 2 +- descarteslabs/core/common/geo/geocontext.py | 33 ++++++++------- 7 files changed, 33 insertions(+), 71 deletions(-) diff --git a/descarteslabs/core/catalog/band.py b/descarteslabs/core/catalog/band.py index 47a56773..746ab2ad 100644 --- a/descarteslabs/core/catalog/band.py +++ b/descarteslabs/core/catalog/band.py @@ -810,8 +810,8 @@ class MaskBand(Band): This enables special behavior for this band during rastering. If this is ``True`` and the band appears as the last band in a raster operation (such as - :meth:`descarteslabs.scenes.scenecollection.SceneCollection.mosaic` or - :meth:`descarteslabs.scenes.scenecollection.SceneCollection.stack`) pixels + :meth:`descarteslabs.catalog.imagecollection.ImageCollection.mosaic` or + :meth:`descarteslabs.catalog.imagecollection.ImageCollection.stack`) pixels with a value of 0 in this band will be treated as transparent. """ ) diff --git a/descarteslabs/core/catalog/image.py b/descarteslabs/core/catalog/image.py index 9f1a13db..fed8006c 100644 --- a/descarteslabs/core/catalog/image.py +++ b/descarteslabs/core/catalog/image.py @@ -933,7 +933,6 @@ def _do_upload(self, files, upload_options): return upload - # Scenes functionality def coverage(self, geom): """ The fraction of a geometry-like object covered by this Image's geometry. diff --git a/descarteslabs/core/catalog/tests/test_image_collection.py b/descarteslabs/core/catalog/tests/test_image_collection.py index dac6383f..4cbec6aa 100644 --- a/descarteslabs/core/catalog/tests/test_image_collection.py +++ b/descarteslabs/core/catalog/tests/test_image_collection.py @@ -64,9 +64,6 @@ def test_stack(self): img_stack = ic.stack("nir red", bands_axis=-1) assert img_stack.shape == (2, 122, 120, 2) - # no_alpha = scenes.stack("nir", mask_alpha=False) - # # assert raster not called with alpha once mocks exist - no_mask = ic.stack("nir", mask_alpha=False, mask_nodata=False) assert not hasattr(no_mask, "mask") assert no_mask.shape == (2, 1, 122, 120) @@ -186,9 +183,6 @@ def test_mosaic(self): assert mosaic_only_alpha.shape == (1, 122, 120) assert ((mosaic_only_alpha.data == 0) == mosaic_only_alpha.mask).all() - # no_alpha = scenes.mosaic("nir", mask_alpha=False) - # # assert raster not called with alpha once mocks exist - no_mask = ic.mosaic("nir", mask_alpha=False, mask_nodata=False) assert not hasattr(no_mask, "mask") assert no_mask.shape == (1, 122, 120) @@ -262,7 +256,7 @@ def test_mosaic_no_alpha(self): ) assert hasattr(masked_alt_alpha_band, "mask") - # errors when alternate alpha band is provided but not available in the scene + # errors when alternate alpha band is provided but not available in the image with pytest.raises(ValueError): ic.mosaic(["Clear_sky_days", "Clear_sky_nights"], mask_alpha="alt-alpha") @@ -271,14 +265,14 @@ def test_filter_coverage(self): polygon = shapely.geometry.Point(0.0, 0.0).buffer(3) geocontext = AOI(geometry=polygon) - scenes = ImageCollection( + images = ImageCollection( [ Image(id="foo:bar", geometry=polygon), Image(id="foo:baz", geometry=polygon.buffer(-0.1)), ] ) - assert len(scenes.filter_coverage(geocontext)) == 1 + assert len(images.filter_coverage(geocontext)) == 1 @patch.object(Image, "get", _image_get) @patch.object( @@ -310,7 +304,7 @@ def test_scaling_parameters(self): "cached_bands_by_product", _cached_bands_by_product, ) -class TestSceneCollectionDownload(unittest.TestCase): +class TestImageCollectionDownload(unittest.TestCase): def setUp(self): with patch.object(Image, "get", _image_get): images = [ diff --git a/descarteslabs/core/client/services/metadata/metadata.py b/descarteslabs/core/client/services/metadata/metadata.py index 49dbf460..25a1cccc 100644 --- a/descarteslabs/core/client/services/metadata/metadata.py +++ b/descarteslabs/core/client/services/metadata/metadata.py @@ -271,7 +271,7 @@ def summary( :param str end_datetime: Desired ending timestamp, in any common format. :param float cloud_fraction: Maximum cloud fraction, calculated by data provider. :param float cloud_fraction_0: Maximum cloud fraction, calculated by cloud mask pixels. - :param float fill_fraction: Minimum scene fill fraction, calculated as valid/total pixels. + :param float fill_fraction: Minimum image fill fraction, calculated as valid/total pixels. :param str storage_state: Filter results based on `storage_state` value. Allowed values are `"available"`, `"remote"`, or `None`, which returns all results regardless of `storage_state` value. :param ~descarteslabs.common.property_filtering.filtering.Expression q: @@ -443,7 +443,7 @@ def paged_search( :param str end_datetime: Desired ending timestamp, in any common format. :param float cloud_fraction: Maximum cloud fraction, calculated by data provider. :param float cloud_fraction_0: Maximum cloud fraction, calculated by cloud mask pixels. - :param float fill_fraction: Minimum scene fill fraction, calculated as valid/total pixels. + :param float fill_fraction: Minimum image fill fraction, calculated as valid/total pixels. :param str storage_state: Filter results based on `storage_state` value. Allowed values are `"available"`, `"remote"`, or `None`, which returns all results regardless of `storage_state` value. @@ -583,7 +583,7 @@ def search( :param str end_datetime: Desired ending timestamp, in any common format. :param float cloud_fraction: Maximum cloud fraction, calculated by data provider. :param float cloud_fraction_0: Maximum cloud fraction, calculated by cloud mask pixels. - :param float fill_fraction: Minimum scene fill fraction, calculated as valid/total pixels. + :param float fill_fraction: Minimum image fill fraction, calculated as valid/total pixels. :param str storage_state: Filter results based on `storage_state` value. Allowed values are `"available"`, `"remote"`, or `None`, which returns all results regardless of `storage_state` value. @@ -695,7 +695,7 @@ def ids( :param str end_datetime: Desired ending timestamp, in any common format. :param float cloud_fraction: Maximum cloud fraction, calculated by data provider. :param float cloud_fraction_0: Maximum cloud fraction, calculated by cloud mask pixels. - :param float fill_fraction: Minimum scene fill fraction, calculated as valid/total pixels. + :param float fill_fraction: Minimum image fill fraction, calculated as valid/total pixels. :param str storage_state: Filter results based on `storage_state` value. Allowed values are `"available"`, `"remote"`, or `None`, which returns all results regardless of `storage_state` value. diff --git a/descarteslabs/core/client/services/raster/raster.py b/descarteslabs/core/client/services/raster/raster.py index bda81ea7..a215a5c2 100644 --- a/descarteslabs/core/client/services/raster/raster.py +++ b/descarteslabs/core/client/services/raster/raster.py @@ -231,7 +231,7 @@ def _retry(req, headers=None): class Raster(Service, DefaultClientMixin): """ The Raster API retrieves data from the Descartes Labs Catalog. Direct use of - the Raster API is not recommended. Consider using the Descartes Labs Scenes API instead. + the Raster API is not recommended. Consider using the Descartes Labs Catalog API instead. """ # https://requests.readthedocs.io/en/master/user/advanced/#timeouts @@ -487,7 +487,7 @@ def ndarray( :param bool progress: Display a progress bar. :return: A tuple of ``(np_array, metadata)``. The first element (``np_array``) is - the rastered scene as a NumPy array. The second element (``metadata``) is a + the rastered image as a NumPy array. The second element (``metadata``) is a dictionary containing details about the raster operation that happened. These details can be useful for debugging but shouldn't otherwise be relied on (there are no guarantees that certain keys will be present). @@ -631,7 +631,7 @@ def stack( ``bilinear``, ``cubic``, ``cubicsplice``, ``lanczos``, ``average``, ``mode``, ``max``, ``min``, ``med``, ``q1``, ``q3``). :param str order: Order of the returned array. `image` returns arrays as - ``(scene, row, column, band)`` while `gdal` returns arrays as ``(scene, band, row, column)``. + ``(image, row, column, band)`` while `gdal` returns arrays as ``(image, band, row, column)``. :param str dltile: a dltile key used to specify the resolution, bounds, and srs. :param str processing_level: How the processing level of the underlying data should be adjusted, one of ``toa`` (top of atmosphere) and ``surface``. For @@ -645,8 +645,8 @@ def stack( :return: A tuple of ``(stack, metadata)``. - * ``stack``: 4D ndarray. The axes are ordered ``(scene, band, y, x)`` - (or ``(scene, y, x, band)`` if ``order="gdal"``). The scenes in the outermost + * ``stack``: 4D ndarray. The axes are ordered ``(image, band, y, x)`` + (or ``(image, y, x, band)`` if ``order="gdal"``). The images in the outermost axis are in the same order as the list of identifiers given as ``inputs``. * ``metadata``: List[dict] of the rasterization metadata for each element in ``inputs``. As with the metadata returned by :meth:`ndarray` and :meth:`raster`, these dictionaries @@ -774,35 +774,3 @@ def _construct_npz_params( params["srs"] = tile_params["cs_code"] return params - - def dltile(self, key): - """ - This method has been removed and is no longer included in the documentation. - """ - raise NotImplementedError( - "dltile is removed, use descarteslabs.scenes.DLTile.from_key instead" - ) - - def dltile_from_latlon(self, lat, lon, resolution, tilesize, pad): - """ - This method has been removed and is no longer included in the documentation. - """ - raise NotImplementedError( - "dltile_from_latlon is removed, use descarteslabs.scenes.DLTile.from_latlon instead" - ) - - def dltiles_from_shape(self, resolution, tilesize, pad, shape): - """ - This method has been removed and is no longer included in the documentation. - """ - raise NotImplementedError( - "dltiles_from_shape is removed, use descarteslabs.scenes.DLTile.from_shape instead" - ) - - def iter_tiles_from_shape(self, resolution, tilesize, pad, shape): - """ - This method has been removed and is no longer included in the documentation. - """ - raise NotImplementedError( - "iter_tiles_from_shape is removed, use descarteslabs.scenes.DLTile.iter_from_shape instead" - ) diff --git a/descarteslabs/core/common/display/_display.py b/descarteslabs/core/common/display/_display.py index d81bdbca..81558100 100644 --- a/descarteslabs/core/common/display/_display.py +++ b/descarteslabs/core/common/display/_display.py @@ -42,7 +42,7 @@ def _import_matplotlib_pyplot(): if matplotlib.get_backend() == "MacOSX": raise RuntimeError( "Python is not installed as a framework; the Mac OS X backend will not work.\n" - "To resolve this, *before* calling dl.scenes.display(), execute this code:\n\n" + "To resolve this, *before* calling dl.utils.display(), execute this code:\n\n" "import matplotlib\n" "matplotlib.use('TkAgg')\n" "import matplotlib.pyplot as plt\n\n" diff --git a/descarteslabs/core/common/geo/geocontext.py b/descarteslabs/core/common/geo/geocontext.py index 965f6dfb..70766340 100644 --- a/descarteslabs/core/common/geo/geocontext.py +++ b/descarteslabs/core/common/geo/geocontext.py @@ -40,7 +40,7 @@ class GeoContext(object): Specifies spatial parameters to use when loading a raster from the Descartes Labs catalog. - Two Scenes loaded with the same GeoContext will result in images + Two Images loaded with the same GeoContext will result in images with the same shape (in pixels), covering the same spatial extent, regardless of the dimensions or projection of the original data. @@ -158,11 +158,11 @@ class AOI(GeoContext): .. code-block:: python - cutline_aoi = dl.scenes.AOI(my_geometry, resolution=40) + cutline_aoi = dl.geo.AOI(my_geometry, resolution=40) aoi_with_cutline_disabled = cutline_aoi.assign(geometry=None) - no_cutline_aoi = dl.scenes.AOI(geometry=None, resolution=15, bounds=(-40, 35, -39, 36)) - aoi_without_auto_bounds = dl.scenes.AOI(geometry=my_geometry, resolution=15, bounds=(-40, 35, -39, 36)) - aoi_with_specific_pixel_dimensions = dl.scenes.AOI(geometry=my_geometry, shape=(200, 400)) + no_cutline_aoi = dl.geo.AOI(geometry=None, resolution=15, bounds=(-40, 35, -39, 36)) + aoi_without_auto_bounds = dl.geo.AOI(geometry=my_geometry, resolution=15, bounds=(-40, 35, -39, 36)) + aoi_with_specific_pixel_dimensions = dl.geo.AOI(geometry=my_geometry, shape=(200, 400)) """ __slots__ = ( @@ -691,12 +691,13 @@ class DLTile(GeoContext): ... resolution=10, ... pad=0 ... ) - >>> scenes, ctx = dl.scenes.search(tile, "landsat:LC08:PRE:TOAR") # doctest: +SKIP - >>> Scenes # doctest: +SKIP - SceneCollection of 93 scenes - * Dates: Apr 19, 2013 to Apr 14, 2017 - * Products: landsat:LC08:PRE:TOAR: 93 - >>> ctx # doctest: +SKIP + >>> product = dl.catalog.Product.get("usgs:landsat:oli-tirs:c2:l2:v0") # doctest: +SKIP + >>> images = product.images().intersects(tile).collect() # doctest: +SKIP + >>> images # doctest: +SKIP + ImageCollection of 558 images + * Dates: Mar 18, 2013 to Sep 14, 2023 + * Products: usgs:landsat:oli-tirs:c2:l2:v0: 558 + >>> images.geocontext # doctest: +SKIP DLTile(key='512:0:10.0:13:-17:771', resolution=10.0, tilesize=512, @@ -704,14 +705,14 @@ class DLTile(GeoContext): crs='EPSG:32613', bounds=(412960.0, 3947520.0, 418080.0, 3952640.0), bounds_crs='EPSG:32613', - geometry=, + geometry=, zone=13, ti=-17, tj=771, - geotrans=[ - 412960.0,... 0, - -10.0 - ], ... + geotrans=(412960.0, 10.0, 0.0, 3952640.0, 0.0, -10.0), + proj4='+proj=utm +z...s=m +no_defs ', + wkt='PROJCS["WGS ...SG","32613"]]', + all_touched=False) """ __slots__ = (