Catalog

The Catalog API enables you to upload your own raster data to the Descartes Labs Platform. When you upload data via the Catalog, you are able to interact with the data like any other product on the platform. You can search for your data using the Metadata API, retrieve the data with Raster, and explore the data using the Viewer user interface.

There are two common uses cases relevant to Catalog. First, you may want to use the Catalog API as a part of a larger workflow in which you derive a product from data available through the platform. For example, let’s say you have developed an image classification model. You may use the Metadata API to search for satellite imagery, the Raster API to obtain the imagery, then use the Tasks API to scale the model across a large area. With Catalog, you can add another platform interaction onto the workflow that will upload your new image classifications to the platform as they’re created so that you can visualize and interact with it. In other cases, you may simply want to upload existing data that you have access to but is not hosted by Descartes Labs.

For either of these use cases, you’ll first want to create a new product using the add_product method. This will create a new product in the catalog and allow you to add optional metadata about the product, including the number of bands, resolution, and revisit rate, as well as to grant read access to other users or groups. By default, the product will only be available to your user.

After initializing the product, you next want to add band(s) to the product using the add_band method. Here, you’ll need to reference the input files you will be uploading to the product to best set the required band metadata. For each band, you’ll define the data type, number of bits needed to store the band data, the minimum and maximum values for the band, and also have the option to set additional parameters to define a colormap and optimal scaling for visualization, and define other metadata properties that may be relevant. If you are uploading data from a multiband file, you will also need to indicate which band of the input file to read from using the srcband parameter. If you’re uploading data from a single-band file, the srcband should always be set equal to 1.

After initializing both the product and the band(s), you can now upload your data. In most cases, you’ll want to use the upload_image method. To upload an image, you simply need to specify the path to the file on your file system and the product ID as returned by add_product. When you upload an image, a copy of the image file will be saved in Storage and made accessible through the platform. To upload multiple images, simply iterate over the filenames, passing each filename in a separate call to upload_image.

Some of the functionality of this API is also available through https://catalog.descarteslabs.com. This user interface allows you to create and edit both products and bands. Data uploads can currently only be done through the programmatic interface described here.