privateer-elements-sdk 2025.11.5__tar.gz

privateer_elements_sdk-2025.11.5/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2022 Orbital Insight, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

privateer_elements_sdk-2025.11.5/PKG-INFO

@@ -0,0 +1,470 @@
+Metadata-Version: 2.4
+Name: privateer-elements-sdk
+Version: 2025.11.5
+Summary: A software development kit for developing projects on Elements
+Author: Orbital Insight
+License: Copyright 2022 Orbital Insight, Inc.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+        
+Project-URL: Readme, https://terrascope.readme.io/docs
+Keywords: Orbital Insight,OI,SDK,elements,elements-sdk,API,elements-api
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: grpcio-tools
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: wget
+Requires-Dist: h3
+Requires-Dist: geojson
+Requires-Dist: chardet
+Requires-Dist: click
+Requires-Dist: pyyaml
+Requires-Dist: geopandas
+Requires-Dist: pytz
+Requires-Dist: shapely
+Requires-Dist: tabulate
+Requires-Dist: timezonefinder
+Requires-Dist: elements-api>=2025.11.5
+Requires-Dist: boto3
+Requires-Dist: httpx>=0.24
+Requires-Dist: pyarrow>=14
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: grip; extra == "dev"
+Dynamic: license-file
+
+# Elements SDK
+
+## Description
+
+The Elements Platform is a collection of tools to analyze sensor data over space and time. The Elements SDK 
+(software development kit) is a Python package that simplifies users' interaction with the Elements Platform API.
+
+## Installation
+
+[Readme: Installation](https://elements.readme.io/docs/installation-1)
+
+## Usage
+
+The Elements SDK is designed to simplify access to all the [elements-api](https://pypi.org/project/elements-api/) calls
+that are available. Ensure that you have the correct elements-api package installed.
+
+Each API uses a client object which requires the following env variables to be set:
+
+```shell
+TERRASCOPE_API_HOST=https://terrascope-app.orbitalinsight.com/
+TERRASCOPE_API_TOKEN=<Elements API Token>
+TERRASCOPE_TIMEOUT=<Int timeout in seconds> defaults to 60 seconds
+```
+
+You will always want to ensure that you have the correct elements-sdk version installed. The latest can be found here:
+https://pypi.org/project/elements-sdk/
+
+To manually build a local version of the elements-sdk (for example, if you are making changes and want to test):
+1. Update the version specified in the `pyproject.toml` file, e.g. `version = "1.0.6.1"` (must be `pep440`)
+2. Execute from the top-level elements_sdk folder: `python3 -m build`. If you don't have the `build` package run `pip3 install build`
+3. `cd dist/`
+4. `pip3 install elements_sdk-1.0.6-test-py3-none-any.whl` (this file name may be different based on the version specified)
+
+
+# CLI Usage #
+
+## Installation ##
+
+1. Pip install elements-sdk
+
+```
+$ pip install elements-sdk
+````
+
+If you're a developer working on the CLI itself, you may want to add [extras] in the installation.  This will include aditional packages which are used for building and testing the command line tool:
+
+```
+$ pip install 'elements-sdk[extras]'
+```
+
+2. Set some environment variables (here stashed in a 'source.sh' file).
+
+```
+$ cat source.sh
+export TERRASCOPE_API_HOST=api-papi.qa3.orbitalinsight.io
+export TERRASCOPE_AUTHOR=you@yourdomain.com
+export TERRASCOPE_API_ADMIN_TOKEN=<YOUR ADMIN TOKEN>
+export TERRASCOPE_API_TOKEN=<YOUR USER TOKEN>
+
+$ source source.sh
+```
+
+# Basic usage #
+
+The executible is installed as the `ts` command.  There is a old unix
+'ts' command, but it's rarely used by most developers and hopefully
+this choice does not create any serious problems with naming
+conflicts.
+
+The 'ts' command mirrors the overall structure of Elements itself.  The command tree is heirarchical, with groupings of commands.  The `--help` command shows the layout:
+
+```
+$ ts --help
+Usage: ts [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --help  Show this message and exit.
+
+Command Super-Groups:
+  algorithm  'algorithm' super-group
+  analysis   'analysis' super-group
+  data       'data' super group
+
+Command Groups:
+  aoi            'aoi' command group
+  credit         'credit' command group
+  environment    'environment' command group
+  imagery        'imagery' command group
+  manifest       'manifest' command group
+  permission     'permission' command group
+  tasks          'tasks' command group
+  toi            'toi' command group
+  visualization  'visualization' command group
+```
+
+Any command can be used with a abbreviated for, as long as it's
+unique.  So, `ts algo` is fine to avoid typing `ts algorithm`, but `ts
+a` cannot be disambiguated from `ts analysis` or `ts aoi` commands.
+
+Help is also available for each specific command, e.g. for the `algorithm` command:
+
+```
+$ ts algo --help
+Usage: ts.py algo [OPTIONS] COMMAND [ARGS]...
+
+  'algorithm' super-group
+
+Options:
+  --help  Show this message and exit.
+
+Command Groups:
+  computation  Algorithm 'computation' command group
+  config       Algorithm 'config' command group
+  version      Algorithm 'version' command group
+
+Commands:
+  create    Create an algorithm object (no manifest)
+  get       Get algorithm info
+  register  Create an algorithm, and register it.
+  update    Update an existing algorithm with manifest or pricing.
+```
+
+Each specific subcommand also has help, e.g. the `ts algo get` subcommand:
+
+```
+$ ts alg get --help
+Usage: ts.py algo get [OPTIONS]
+
+  Get algorithm info
+
+Options:
+  -ia, --algorithm_id TEXT
+  -n, --algorithm_name TEXT
+  -t, --truncate INTEGER     Truncate columns to this many characters.  Use 0
+                             for no truncation.  (36 is the length of a full
+                             UUID).
+  -v, --verbose
+  --help                     Show this message and exit.
+```
+
+## Full Command Listing ##
+
+Here is the overall command tree, with comments when it's not self-evident/obvious:
+
+```
+ts
+`- algorithm           # commands related to TS algorithms
+  |--> create          #
+  |--> get             #
+  |--> register        # create an algorithm, algorithm_version, and (optionally) algorithm_config
+  |--> update          # update an existing algorithm by creating a new algo version and (optionally) algo config
+  `- computation       # commands related to TS algorithm computations
+     |--> create       #
+     |--> download     #
+     |--> get          #
+     `--> run          #
+  `- config            # commands related to TS algorithm configs
+     |--> create       #
+     |--> deactivate   # deactivate (but not delete) a config
+     `--> get          #
+  `- version           # commands related to TS algorithm versions
+     |--> create       #
+     |--> deactivate   #
+     `--> get          # get algorithm version info (including the manifest)
+`- analysis            # commands related to TS analyses
+  |--> create          #
+  |--> display         # A sort of 'get'++ command that lists each analysis, +versions, +configs and any computations
+  |--> get             #
+  |--> register        # create an analysis, analysis_version, and (optionally) an analysis_config
+  |--> update          # update an existing analysis by creating a new analysis_version, and config
+  `- computation       # commands related to TS analysis computations
+     |--> create       #
+     |--> download     #
+     |--> get          #
+     `--> run          #
+  `- config            # commands related to TS analysis configs
+     |--> create       #
+     |--> deactivate   #
+     `--> get          #
+   ` version           # commands related to TS analysis versions
+     |--> create       #
+     `--> get          # get analysis version info (including the analysis manifest)
+`- data                # commands related to TS data types and sources
+  `- source            # TS data sources
+     | --> get         #
+     ` --> list        # list all available data sources
+  `- type              # TS data types
+     | --> get         #
+     ` --> list        # list all available data types
+`- aoi                 #
+  |--> create          #
+  |--> delete          #
+  |--> get             #
+  |--> list            #
+  `--> update          #
+`- tasks               # IMPORTANT - tasks commands live here
+  |- initialize        # register an algo + analysis ... soup to nuts.
+   ` update            # update an algo + analysis ... end to end.
+`- environment         #
+  `--> check           # verify the environment
+`- imagery             #
+  `--> search          # search the scenes (ingested) or catalog (orderable) for available images of an AOI/TOI
+`- permission          #
+  |--> get             # list users with READ permission on analysis
+  `--> set             # set READ permission for an algorithm analysis with another user (i.e. share it)
+`- credit              #
+  |--> get             # get credit price for analysis (not yet working)
+  `--> set             # set the credit pricing for an analysis
+`- toi                 #
+  |--> create          #
+  |--> delete          #
+  `--> get             #
+`- visualization       #
+  |--> create          #
+  `--> get             #
+```
+
+
+## General Command Patterns ##
+
+The commands generally try to use the same options for the same types
+of inputs.  For example, IDs like algorithm_id or analysis_config_id,
+will start with 'i' and then a character to denote type of ID
+... e.g. `-ia <algorithm_id>`, or `-iv <algorithm_version_id>`.  For
+things associated with algorithms, the second character will be lower
+case, and for things associated with analysis, the second character
+will be upper case.
+
+
+Here are the main ones that *usually* follow the rules:
+```
+-i   - IDs
+
+-ia  - algorithm_id
+-iv  - algorithm_version_id
+-ic  - algorithm_config_id
+-ip  - algorithm_computation_id
+
+-iA  - anlaysis_id
+-iV  - analysis_version_id
+-iC  - analysis_config_id
+-iP  - analysis_computation_id
+
+-n   - names
+
+-na  - algorithm_name
+-nc  - algorithm_config_name
+-nA  - analysis_name
+-nC  - analysis_config_name
+```
+
+### The Most Frequently Used Commands ###
+
+The `ts` CLI allows you to perform pretty surgical operations in
+Elements, and most of the commands do very specialized things which
+you won't usually need.  For common tasks, there are `tasks` commands
+to carry out things that would normally take many commands.  For
+example, in order to register a new algorithm and create an analysis
+to run it through the Elements UI, you normally use the following
+commands (specific options are not shown here):
+
+```
+$ ts algo create
+$ ts algo version create
+$ ts algo config create
+$ ts analysis create
+$ ts analysis version create
+$ ts analysis config create
+```
+
+All of these commands are bundled together in the `ts tasks init`
+command.  If you require surgical control of algorithm registration,
+you have it.  But generally, the `tasks` commands will probably suit
+most needs.
+
+#### Get algorithm info ####
+
+```
+$ ts alg get -na hlnorm
+                 name                          algorithm_id                    author
+0  hlnorm_foottraffic  deadbeef-5c5a-48d9-b65a-3748ebf9bb8e  wally@orbitalinsight.com
+```
+
+#### Look up Data Source and Data Type ####
+
+This is useful when preparing a manifest to register an algorithm.
+Data sources and types must be among those supported by elements.
+To get a listing of the current set, do this:
+
+```
+$ ts data source list
+```
+
+```
+$ ts data type list
+```
+
+#### Create a New Algorithm + Analysis ####
+
+To put in a new algorithm and analysis, you have to create a manifest,
+and then you can submit it with:
+
+```
+$ ts tasks init -m <manifest_yaml> -nC <analysis_config_name (appears in UI)>
+```
+
+That will create the algorithm, algorithm_version, algorithm_config, analysis, analysis_version, and analysis_config.
+
+
+#### Update an Algorithm + Analysis ####
+
+```
+$ ts tasks update -m <manifest_yaml> -nC <analysis_config_name> -ia <algo_id> -iA <analysis_id> -V <new version>
+```
+
+#### Share an analysis with another user ####
+
+```
+$ ts perm set -iC <analysis_config_id> -u <username1> <username2> ...
+```
+
+
+### Finding IDs ###
+
+Elements uses UUIDs to identify pretty much everything, and you
+often need to get these in order to carry out certain operations.
+Here are some of the most useful:
+
+
+#### Dump IDs for an Analysis ####
+
+This is a heirarchical dump of any analyses matching <search_string>,
+and their analysis_versions, analysis_configs, and any computations
+(there are options to filter the computations by date if there are too
+many).
+
+```
+$ ts analysis display -nA <analysis_name_search_string>
+```
+
+#### Look up algorithm_id for an Analysis ####
+
+Do find out info about an algorithm node in an analysis, query the
+analysis version with `-C all` (get all available columns), and `-T`
+(transpose ... so the output is readable).  The algorithm info is
+buried in the printout.
+
+```
+ts ana version get -iV <analysis_version_id> -C all -T
+```
+
+
+### Testing an Algorithm ###
+
+#### Checking for available imagery ####
+
+In the examples:
+
+- `-S <shapefile>` contains the AOI you wish to find imagery for
+- `-ia <aoi_id>` refers to the id of an AOI in the provided shapefile (aois.geojson here).
+- `-d` specifies the data source,
+- `-p` specifies the 'processing spec' (not queryable through the API, you just have to know it).
+- `-ts <start_time>`
+- `-te <end_time>`
+- `-s <search_service>` can be either 'SCENE' (already ingested images) or 'CATALOG' (available to order)
+
+```
+$ ts image search -S aois.geojson -ia <aoi_id> -ts 2023-01-08 -te 2023-01-31 -d planet_PSSceneSD -p PL-PSSceneSR -s CATALOG
+```
+
+
+#### Create and Run an algorithm computation ####
+
+(-f 3 means 'daily')
+
+```
+$ ts comp create -iC <algo_config_id> -s 2022-01-01 -e 2022-01-07 -a ./myaois.geojson -f 3
+```
+
+The above example to create a computation will print out a computation_id.  Use it to run:
+
+```
+$ ts comp run -ip <comp_id>
+```
+
+#### Get info about the computation ####
+
+```
+$ ts comp get -ip <computation_id>
+
+ecb494a3-e0e1-4c7b-804b-af45067816ba
+id                   ecb494a3-e0e1-4c7b-804b-af45067816ba
+aoi_collection_id    58111acf-50d8-4079-a562-6a98badd75da
+algo_config_id       6b995056-dd72-494f-b7ce-abf27422d6f1
+toi_id               aafe2b93-8f80-4cf8-994b-97ab43d346ec
+submitted_on         2023-03-24T03:52:01.245849Z
+state                COMPLETE
+last_execution       2023-03-24T03:59:02.243957Z
+progress.succeeded   100.0
+```
+
+
+#### Download computation results ####
+
+```
+$ ts algo comp download -ip <computation_id> -o test_result.zip
+```
+
+## New Module Functions ##
+
+* The async functions that make the calls to the SDK live in `elements/cli/lib/workflow.py`
+* Most are short and sweet.  Feel free to add what you need.
+
+
+## Authors and acknowledgment
+
+Orbital Insight
+
+## License
+
+[LICENSE](LICENSE)
+