Merge pull request #46 from descarteslabs/feat/shapes

Breaks API, renames shapes/places/locations/geoms.

Author: samskillman

descarteslabs/scripts/metadata

@@ -30,7 +30,7 @@ if __name__ == "__main__":
     parser.add_argument('argument', nargs='?')
 
     parser.add_argument('-url', help='The url of the service')
-    parser.add_argument('-shape', help='A slug for a named shape')
+    parser.add_argument('-place', help='A slug for a named place')
     parser.add_argument('-const_id', default=None, help='Constellation ID', nargs='+')
     parser.add_argument('-start_time', help='Start of valid date/time range (inclusive)')
     parser.add_argument('-end_time', help='End of valid date/time range (inclusive)')
@@ -58,8 +58,8 @@ if __name__ == "__main__":
 
     if args.command == 'summary':
 
-        if args.shape:
-            kwargs['shape'] = args.shape
+        if args.place:
+            kwargs['place'] = args.place
         if args.const_id:
             kwargs['const_id'] = args.const_id
         if args.start_time:
@@ -79,8 +79,8 @@ if __name__ == "__main__":
 
     if args.command == 'search':
 
-        if args.shape:
-            kwargs['shape'] = args.shape
+        if args.place:
+            kwargs['place'] = args.place
         if args.const_id:
             kwargs['const_id'] = args.const_id
         if args.start_time:
@@ -104,8 +104,8 @@ if __name__ == "__main__":
 
     if args.command == 'keys':
 
-        if args.shape:
-            kwargs['shape'] = args.shape
+        if args.place:
+            kwargs['place'] = args.place
         if args.const_id:
             kwargs['const_id'] = args.const_id
         if args.start_time:

descarteslabs/scripts/places

@@ -24,7 +24,7 @@ if __name__ == "__main__":
 
     parser = argparse.ArgumentParser()
 
-    parser.add_argument('command', choices=['find', 'shape', 'prefix', 'placetypes'],
+    parser.add_argument('command', choices=['find', 'place', 'prefix', 'placetypes'],
                         help='The action to take.')
     parser.add_argument('argument', nargs='?')
 

descarteslabs/services/metadata.py

@@ -49,14 +49,14 @@ def sources(self):
 
         return r.json()
 
-    def summary(self, const_id=None, date='acquired', part='day', shape=None, geom=None, start_time=None, end_time=None,
+    def summary(self, const_id=None, date='acquired', part='day', place=None, geom=None, start_time=None, end_time=None,
                 params=None, bbox=False, direct=False):
         """Get a summary of the results for the specified spatio-temporal query.
 
         :param list(str) const_id: Constellation identifier(s).
         :param str date: The date field to use for search (e.g. `acquired`).
         :param str part: Part of the date to aggregate over (e.g. `day`).
-        :param str shape: A slug identifier to be used as a region of interest.
+        :param str place: A slug identifier to be used as a region of interest.
         :param str geom: A GeoJSON or WKT region of interest.
         :param str start_time: Desired starting date and time (inclusive).
         :param str end_time: Desired ending date and time (inclusive).
@@ -65,7 +65,7 @@ def summary(self, const_id=None, date='acquired', part='day', shape=None, geom=N
 
         Example usage::
 
-            >>> metadata.summary(shape='north-america_united-states_iowa',
+            >>> metadata.summary(place='north-america_united-states_iowa',
                     const_id=['L8'], part='year')
 
             [{'bytes': 187707322653,
@@ -93,11 +93,15 @@ def summary(self, const_id=None, date='acquired', part='day', shape=None, geom=N
                     'pixels': 18087390976}],
                 'pixels': 367993294400}]
         """
-        if shape:
-            waldo = Places()
-            shape = waldo.shape(shape, geom='low')
+        if place:
+            places = Places()
+            places.auth = self.auth
+            shape = places.shape(place, geom='low')
             geom = json.dumps(shape['geometry'])
 
+        if isinstance(geom, dict):
+            geom = json.dumps(geom)
+
         kwargs = {}
 
         if date:
@@ -143,14 +147,14 @@ def f(x):
 
         return result
 
-    def search(self, const_id=None, date='acquired', shape=None, geom=None, start_time=None, end_time=None, params=None,
+    def search(self, const_id=None, date='acquired', place=None, geom=None, start_time=None, end_time=None, params=None,
                limit=100, offset=0, bbox=False, direct=False):
         """Search metadata given a spatio-temporal query. All parameters are
         optional. Results are paged using limit/offset.
 
         :param list(str) const_id: Constellation identifier(s).
         :param str date: The date field to use for search (e.g. `acquired`).
-        :param str shape: A slug identifier to be used as a region of interest.
+        :param str place: A slug identifier to be used as a region of interest.
         :param str geom: A GeoJSON or WKT region of interest.
         :param str start_time: Desired starting date and time (inclusive).
         :param str end_time: Desired ending date and time (inclusive).
@@ -163,19 +167,21 @@ def search(self, const_id=None, date='acquired', shape=None, geom=None, start_ti
 
         Example::
 
-            >>> scenes = metadata.search(shape='north-america_united-states_iowa', const_id=['L8'],
+            >>> scenes = metadata.search(place='north-america_united-states_iowa', const_id=['L8'],
                     start_time='2016-07-01', end_time='2016-07-31 23:59:59')
                 len(scenes['features'])
 
             34
         """
-        if shape:
-            waldo = Places()
-
-            shape = waldo.shape(shape, geom='low')
-
+        if place:
+            places = Places()
+            places.auth = self.auth
+            shape = places.shape(place, geom='low')
             geom = json.dumps(shape['geometry'])
 
+        if isinstance(geom, dict):
+            geom = json.dumps(geom)
+
         kwargs = {}
 
         kwargs['limit'] = limit
@@ -215,14 +221,14 @@ def f(x):
 
         return result
 
-    def keys(self, const_id=None, date='acquired', shape=None, geom=None, start_time=None, end_time=None, params=None,
+    def keys(self, const_id=None, date='acquired', place=None, geom=None, start_time=None, end_time=None, params=None,
              limit=100, offset=0, bbox=False, direct=False):
         """Search metadata given a spatio-temporal query. All parameters are
         optional. Results are paged using limit/offset.
 
         :param list(str) const_id: Constellation identifier(s).
         :param str date: The date field to use for search (e.g. `acquired`).
-        :param str shape: A slug identifier to be used as a region of interest.
+        :param str place: A slug identifier to be used as a region of interest.
         :param str geom: A GeoJSON or WKT region of interest.
         :param str start_time: Desired starting date and time (inclusive).
         :param str end_time: Desired ending date and time (inclusive).
@@ -235,7 +241,7 @@ def keys(self, const_id=None, date='acquired', shape=None, geom=None, start_time
 
         Example::
 
-            >>> metadata.keys(shape='north-america_united-states_iowa', const_id=['L8'],
+            >>> metadata.keys(place='north-america_united-states_iowa', const_id=['L8'],
                     start_time='2016-07-01', end_time='2016-07-31 23:59:59')
 
             [
@@ -245,19 +251,19 @@ def keys(self, const_id=None, date='acquired', shape=None, geom=None, start_time
                 ...
             ]
         """
-        result = self.search(const_id, date, shape, geom, start_time, end_time, params, limit, offset, bbox, direct)
+        result = self.search(const_id, date, place, geom, start_time, end_time, params, limit, offset, bbox, direct)
 
         return [feature['id'] for feature in result['features'][:limit]]
 
-    def features(self, const_id=None, date='acquired', shape=None, geom=None, start_time=None, end_time=None,
+    def features(self, const_id=None, date='acquired', place=None, geom=None, start_time=None, end_time=None,
                  params=None, limit=100, bbox=False, direct=False):
         """Generator that combines summary and search to page through results.
 
         :param int limit: Number of features to fetch per request.
 
         :return: Generator of GeoJSON ``Feature`` objects.
         """
-        result = self.summary(const_id=const_id, date=date, shape=shape, geom=geom, start_time=start_time,
+        result = self.summary(const_id=const_id, date=date, place=place, geom=geom, start_time=start_time,
                               end_time=end_time, params=params, bbox=bbox, direct=direct)
 
         for summary in result:
@@ -269,7 +275,7 @@ def features(self, const_id=None, date='acquired', shape=None, geom=None, start_
 
             while offset < count:
 
-                features = self.search(const_id=[const_id], date=date, shape=shape, geom=geom, start_time=start_time,
+                features = self.search(const_id=[const_id], date=date, place=place, geom=geom, start_time=start_time,
                                        end_time=end_time, params=params, limit=limit, offset=offset, bbox=bbox,
                                        direct=direct)
 

descarteslabs/services/raster.py

@@ -105,8 +105,8 @@ def raster(
             resolution=None,
             bounds=None,
             bounds_srs=None,
-            shape=None,
-            location=None,
+            cutline=None,
+            place=None,
             align_pixels=False,
             resampler=None,
     ):
@@ -125,21 +125,22 @@ def raster(
         :param str srs: Output spatial reference system definition understood by GDAL.
         :param float resolution: Desired resolution in output SRS units.
         :param tuple outsize: Desired output (width, height) in pixels.
-        :param str shape: A GeoJSON feature to be used as a cutline.
-        :param str location: A slug identifier to be used as a cutline.
+        :param str cutline: A GeoJSON feature or geometry to be used as a cutline.
+        :param str place: A slug identifier to be used as a cutline.
         :param tuple bounds: ``(min_x, min_y, max_x, max_y)`` in target SRS.
         :param str bounds_srs: Override the coordinate system in which bounds are expressed.
         :param bool align_pixels: Align pixels to the target coordinate system.
         :param str resampler: Resampling algorithm to be used during warping (``near``,
             ``bilinear``, ``cubic``, ``cubicsplice``, ``lanczos``, ``average``, ``mode``,
             ``max``, ``min``, ``med``, ``q1``, ``q3``).
         """
-        shape = as_json_string(shape)
+        cutline = as_json_string(cutline)
 
-        if location:
+        if place:
             places = Places()
-            shape = places.shape(location, geom='low')
-            shape = json.dumps(shape['geometry'])
+            places.auth = self.auth
+            shape = places.shape(place, geom='low')
+            cutline = json.dumps(shape['geometry'])
 
         params = {
             'keys': inputs,
@@ -149,7 +150,7 @@ def raster(
             'of': output_format,
             'srs': srs,
             'resolution': resolution,
-            'shape': shape,
+            'shape': cutline,
             'outputBounds': bounds,
             'outputBoundsSRS': bounds_srs,
             'outsize': dimensions,
@@ -178,8 +179,8 @@ def ndarray(
             srs=None,
             resolution=None,
             dimensions=None,
-            shape=None,
-            location=None,
+            cutline=None,
+            place=None,
             bounds=None,
             bounds_srs=None,
             align_pixels=False,
@@ -194,12 +195,13 @@ def ndarray(
             ``(row, column, band)`` while `gdal` returns arrays as ``(band, row, column)``.
 
         """
-        shape = as_json_string(shape)
+        cutline = as_json_string(cutline)
 
-        if location is not None:
+        if place is not None:
             places = Places()
-            shape = places.shape(location, geom='low')
-            shape = json.dumps(shape['geometry'])
+            places.auth = self.auth
+            shape = places.shape(place, geom='low')
+            cutline = json.dumps(shape['geometry'])
 
         params = {
             'keys': inputs,
@@ -208,7 +210,7 @@ def ndarray(
             'ot': data_type,
             'srs': srs,
             'resolution': resolution,
-            'shape': shape,
+            'shape': cutline,
             'outputBounds': bounds,
             'outputBoundsSRS': bounds_srs,
             'outsize': dimensions,

descarteslabs/tests/test_metadata.py

@@ -18,7 +18,7 @@
 from .helpers import is_external_user
 
 
-class TestRuncible(unittest.TestCase):
+class TestMetadata(unittest.TestCase):
     instance = None
 
     @classmethod
@@ -47,9 +47,9 @@ def test_multiple_const_id(self):
         r = self.instance.search(start_time='2016-09-01', end_time='2016-09-02', const_id=['L8', 'L7'])
         self.assertGreater(len(r['features']), 0)
 
-    @unittest.skip("search by shape name not currently supported")
-    def test_shape(self):
-        r = self.instance.search(shape='north-america_united-states_iowa', limit=1)
+    @unittest.skipIf(is_external_user(), "currently requires internal user")
+    def test_place(self):
+        r = self.instance.search(const_id=['L8'], place='north-america_united-states_iowa', limit=1)
         self.assertEqual(1, len(r['features']))
 
     def test_summary(self):

descarteslabs/tests/test_raster.py

@@ -13,10 +13,11 @@
 # limitations under the License.
 
 import unittest
+import json
 
 import descarteslabs as dl
 from descarteslabs.addons import numpy as np
-from .helpers import is_external_user
+from descarteslabs.tests.helpers import is_external_user
 
 
 class TestRaster(unittest.TestCase):
@@ -68,6 +69,48 @@ def test_ndarray_single_band(self):
         except ImportError:
             pass
 
+    @unittest.skipIf(is_external_user(), "currently requires internal user")
+    def test_cutline_dict(self):
+        shape = {"geometry":
+                 {"type": "Polygon",
+                  "coordinates": [[[-95.2989209, 42.7999878], [-93.1167728, 42.3858464],
+                                   [-93.7138666, 40.703737], [-95.8364984, 41.1150618],
+                                   [-95.2989209, 42.7999878]]]
+                  }
+                 }
+        try:
+            data, metadata = self.raster.ndarray(
+                    inputs=['meta_LC80270312016188_v1'],
+                    bands=['red'],
+                    resolution=960,
+                    cutline=shape,
+                    )
+            self.assertEqual(data.shape, (245, 238))
+            self.assertEqual(data.dtype, np.uint16)
+            self.assertEqual(len(metadata['bands']), 1)
+        except ImportError:
+            pass
+
+    @unittest.skipIf(is_external_user(), "currently requires internal user")
+    def test_cutline_str(self):
+        shape = {"geometry":
+                 {"type": "Polygon",
+                  "coordinates": [[[-95.2989209, 42.7999878], [-93.1167728, 42.3858464],
+                                   [-93.7138666, 40.703737], [-95.8364984, 41.1150618],
+                                   [-95.2989209, 42.7999878]]]}}
+        try:
+            data, metadata = self.raster.ndarray(
+                    inputs=['meta_LC80270312016188_v1'],
+                    bands=['red'],
+                    resolution=960,
+                    cutline=json.dumps(shape),
+                    )
+            self.assertEqual(data.shape, (245, 238))
+            self.assertEqual(data.dtype, np.uint16)
+            self.assertEqual(len(metadata['bands']), 1)
+        except ImportError:
+            pass
+
     @unittest.skipIf(is_external_user(), "currently requires internal user")
     def test_thumbnail(self):
         r = self.raster.raster(
@@ -96,7 +139,7 @@ def test_landsat8_bands(self):
             self.assertTrue(band in r)
 
     @unittest.skipIf(is_external_user(), "currently requires internal user")
-    def test_dlkeys_from_shape(self):
+    def test_dlkeys_from_place(self):
         iowa = self.places.shape('north-america_united-states_iowa', geom='low')
         iowa_geom = iowa['geometry']
         dlkeys_geojson = self.raster.dlkeys_from_shape(30.0, 2048, 16, iowa_geom)