diff --git a/clients/python/sliderule/sliderule.py b/clients/python/sliderule/sliderule.py index 0e081c099..a99cf29cc 100644 --- a/clients/python/sliderule/sliderule.py +++ b/clients/python/sliderule/sliderule.py @@ -1221,29 +1221,59 @@ def toregion(source, tolerance=0.0, cellsize=0.01, n_clusters=1): dict a list of longitudes and latitudes containing the region of interest that can be used for the **poly** and **raster** parameters in a processing request to SlideRule. - region = {"poly": [{"lat": , "lon": }, ...], "clusters": [[{"lat": , "lon": }, ...], [{"lat": , "lon": }, ...]], "raster": {"data": , "length": , "cellsize": }} + region = { + + "gdf": + + "poly": [{"lat": , "lon": }, ...], + + "raster": {"data": , + + "clusters": [[{"lat": , "lon": }, ...], [{"lat": , "lon": }, ...]] } Examples -------- - >>> from sliderule import icesat2 - >>> # Region of Interest # - >>> region_filename = sys.argv[1] - >>> region = sliderule.toregion(region_filename) - >>> # Configure SlideRule # - >>> icesat2.init("slideruleearth.io", False) - >>> # Build ATL06 Request # - >>> parms = { - ... "poly": region["poly"], - ... "srt": icesat2.SRT_LAND, - ... "cnf": icesat2.CNF_SURFACE_HIGH, - ... "ats": 10.0, - ... "cnt": 10, - ... "len": 40.0, - ... "res": 20.0, - ... "maxi": 1 - ... } - >>> # Get ATL06 Elevations - >>> atl06 = icesat2.atl06p(parms) + >>> import sliderule, json + >>> region = sliderule.toregion("tests/data/grandmesa.geojson") + >>> print(json.dumps(region["poly"], indent=4)) + [ + { + "lon": -108.20772968780051, + "lat": 38.8232055291981 + }, + { + "lon": -108.07460164311031, + "lat": 38.8475137825863 + }, + { + "lon": -107.72839858755752, + "lat": 39.01510930230633 + }, + { + "lon": -107.78724142490994, + "lat": 39.195630349659986 + }, + { + "lon": -108.17287000970857, + "lat": 39.15920066396116 + }, + { + "lon": -108.31168256553767, + "lat": 39.13757646212944 + }, + { + "lon": -108.34115668325224, + "lat": 39.03758987613325 + }, + { + "lon": -108.2878686387796, + "lat": 38.89051431295789 + }, + { + "lon": -108.20772968780051, + "lat": 38.8232055291981 + } + ] ''' tstart = time.perf_counter() diff --git a/docs/rtd/source/user_guide/SlideRule.rst b/docs/rtd/source/user_guide/SlideRule.rst index a255e7f36..bf9c89ce4 100644 --- a/docs/rtd/source/user_guide/SlideRule.rst +++ b/docs/rtd/source/user_guide/SlideRule.rst @@ -22,7 +22,7 @@ Using SlideRule means issuing HTTP requests to SlideRule's endpoints to perform The SlideRule Python Client helps make the above steps a lot easier by providing a user-friendly interface for accomplishing typical workflows. -#. The Python client supports an *area of interest* being defined in multiple ways - as a dictionary of latitude and longitudes, a list of coordinates, a GeoJSON file, a Shapefile, or a GeoDataFrame - and then representing the area of interest in standard formats accepted by SlideRule and other NASA web services. +#. The Python client supports an *area of interest* being defined in multiple ways - as a dictionary of latitude and longitudes, a list of coordinates, a GeoJSON file, a Shapefile, or a GeoDataFrame - and then converting that representation into the different forms required by SlideRule and other NASA web services. #. The Python client queries NASA's Common Metadata Repository (CMR) system automatically for the user and populates the requests to SlideRule with the available science data pertinent to the user's request. #. The Python client allows users to define their processing parameters as Python dictionaries, and make requests to SlideRule using Python functions. #. The Python client handles the HTTPS connection to the SlideRule servers as well as any necessary authentication requests to the SlideRule Provisioning System when private clusters are being used. @@ -138,7 +138,7 @@ For example: {"lon": -108.3605610678553, "lat": 39.25086131372244}, {"lon": -108.3435200747503, "lat": 38.89102961045247} ] -In order to facilitate other formats, the ``sliderule.toregion`` function can be used to convert polygons from the GeoJSON and Shapefile formats to the format accepted by `SlideRule`. +In order to facilitate other formats, the ``sliderule.toregion`` function can be used to convert polygons from the GeoJSON and Shapefile formats into this format accepted by `SlideRule`. There is no limit to the number of points in the polygon, but note that as the number of points grow, the amount of time it takes to perform the subsetting process also grows. For that reason, it is recommended that if your polygon has more than a few hundred points, it is best to enable the rasterization option described in the GeoJSON section below.