User GuideAPI ReferenceWhat's NewQuick Tutorials
ContactAbout Us

Project Creation

Suggest Edits

Project Creation

A Project is the main resource in the GO system. In the previous section of this Guide, you saw how
to create, retrieve, modify, and delete a project, using just three of the project's fields: its
name, description, and id.

In this section, we will show how to set the types of detection and analysis algorithms to be run,
the areas of the Earth to look at, the time periods to analyze, and more. We will begin to
understand the major resource types in the GO API: Project, Version, AOI, and Algorithm.

In later sections, we will introduce the Job resource, used to execute a Project, and the Result
resource, used to hold the output of the Project's execution.

The Project Resource

We will begin by creating an empty Project, just as we did before:

POST /project

(Refer to the previous sections to see how to execute that HTTP operation using curl.)

We will use the same request body:

{
    "name": "looking_glass",
    "description": "the looking glass project"
}

and our newly-created (and so far empty) project will look like this:

{
  "data": {
    "algorithm_ids": [],
    "collaborator_ids": [],
    "created_ts": "2019-08-12T15:54:20.902000+00:00",
    "description": "the looking glass project",
    "id": "O1ymF8uopj-190812",
    "name": "looking_glass",
    "owner_id": "alice",
    "parent_project_id": null,
    "stage": "NOT_STARTED",
    "version_ids": [
      "O1ymF8uopj-190812-1.0.0"
    ]
  },
  "status": 201
}

The status value of 201 indicates the resource object was successfully created.

Some of the project's important fields are:

  • algorithm_ids: the names of the detection or analytic algorithms used by this project (list
    of strings)
  • collaborator_ids: the ids of any users who also have access to this project (list of strings)
  • created_ts: the date and time this project was created, in UTC (string)
  • description: text providing information about this project (string)
  • id: the unique identifier for this project (string)
  • name: the name of this project (string)
  • owner_id: the id of the owner of this project (string)
  • stage: the status of this project (string)
  • version_ids: the ids of the Version objects of this project (list of strings)

The other fields in the returned object are for more advanced usage scenarios or are reserved for
internal use.

The Version Resource

Our Project has a version_ids field with one item in it. Each Project begins with one Version
in it, and most of the project's parameters -- the area of interest, the algorithm type, etc. --
are going to be associated with that version. Project versions allow your project to, among other
things, be upgraded as our internal algorithms change; for the purposes of this guide, we will
just be using the initial, default version.

Let's retrieve the version information for the initial version in our project by using its
endpoint:

GET /projects/$P/versions/$V

(Note that the version's id, $V, is formed from the project id and a numeric key like
1.2.3.)

We will get something like this returned:

.. literalinclude:: ../outputs/includes/4_2_get_version_output.json
:language: json

{
  "data": {
    "algorithm_instance_id": null,
    "cloud_cover": 0,
    "creation_ts": "2019-08-12 15:54:22.219000",
    "enabled": true,
    "end_date": "2019-08-08",
    "full_provider_search": true,
    "is_open": false,
    "lucd_cadence": "monthly",
    "lucd_classes": [
      "..."
    ],
    "project_id": "O1ymF8uopj-190812",
    "query_id": "O1ymF8uopj-190812-1.0.0",
    "run_freq_sec": 86400,
    "sampling_period": {
      "unit": "days",
      "value": 15
    },
    "stage": "NOT_STARTED",
    "start_date": "2019-07-09",
    "system_limits": {
      "...": "..."
    },
    "time_tolerance": {
      "unit": "days",
      "value": 2
    }
  },
  "status": 200
}

The key fields in the Version resource are:

  • cloud_cover: the maximum allowed area of cloud cover on any given image used as part of the
    project, expressed as a fraction of the total area (float, between 0.0 and 1.0)
  • creation_ts: the date and time this project was created, in UTC (string)
  • end_date: the end of the date range used for this project's detections, in UTC (string)
  • is_open: if True, indicates this project does not have an end date set and so will continue
    to be run as new data becomes available (boolean)
  • project_id: the project that this version belongs to (string)
  • query_id: the id of this Version resource
  • start_date: the start of the date range used for this project's detections, in UTC (string)

The AOI Resource

We will now -- finally! -- begin to set up our project's parameters. As a simple test, we are
going to be counting cars in downtown San Francisco during the first six months of 2017, and our
first task will be to define the area of interest (AOI).

Adding an AOI is done with a POST to the Version's endpoint. The JSON request should contain
just a name for the AOI and a polygon, formatted as a string using the standard WKT notation for
polygons:

{
    "boundary_wkt": "POLYGON ((-122.408 37.784, -122.401 37.789, -122.392 37.781, -122.398 37.776, -122.408 37.784))",
    "name": "downtown SF"
}

The HTTP operation is:

POST /project/$P/versions/$V/aois

That operation will return a result like:

{
  "data": {
    "aoi_entity_id": "...",
    "aoi_entity_name": "...",
    "area_km2": 0.9728563718130099,
    "boundary_kml": "",
    "boundary_wkt": "POLYGON ((-122.4080000000000013 37.7839999999999989, -122.4009999999999962 37.7890000000000015, -122.3919999999999959 37.7809999999999988, -122.3979999999999961 37.7760000000000034, -122.4080000000000013 37.7839999999999989))",
    "centroid_kml": "",
    "centroid_wkt": "POINT (-122.3998408710218 37.78253266331659)",
    "id": "6f2c5728-f096-4b3e-9773-efd5cded9b97",
    "name": "downtown SF",
    "project_id": "O1ymF8uopj-190812"
  },
  "status": 201
}

Like the Project and Version resources, the AOI has an id field (note, however, that the format
of the string is somewhat different). You can retrieve all of the AOIs for a version resource by
performing a GET on the endpoint /project/$project_id/version/$version_id/aois. You can
also use the AOI id to retrieve or modify the AOI by performing a GET or PUT on
/project/$P/version/$V/aois/$A.

The major fields of the AOI resource are:

  • area_km2: the area, in square kilometers, of the AOI; this is computed for you by GO from
    the boundary_wkt (float)
  • boundary_wkt: the WKT POLYGON describing the shape of the AOI (string)
  • centroid_wkt: the WKT POINT describing the centroid of the AOI; this is computed for you by
    GO from the boundary_wkt (string)
  • id: the id of this AOI (string)
  • name: the human-readable name of this AOI
  • project_id: the d of the project this AOI belongs to (string)

The Algorithm Resource

Next, we will set the algorithm for our project.

The list of available algorithms is stored in the system_limits.algorithm_whitelist field of
the Version resource. It should contain a list of items that look like this:

[
  {
    "CAR_DETECTOR_ANALYSIS": {
      "algorithm_instance_whitelist": [
        "cars_digital_globe_ds_v2.0.0",
        "cars_astrium_ds_v2.0.0"
      ],
      "description": "Detecting cars in high res imagery.",
      "name": "cars"
    }
  },
  {
    "MULTICLASS_AIRCRAFT_DETECTOR_ANALYSIS": {
      "algorithm_instance_whitelist": [
        "multiclass_aircrafts_analysis_dg_ds_v3.0.0"
      ],
      "description": "Detecting and classifying commercial and military aircrafts in high res imagery.",
      "name": "Aircraft (Commercial, Fighter, Bomber, Other)"
    }
  },
  "..."
]

The name and description fields indicate what the algorithms do. The
algorithm_instance_whitelist is used to identify the specific algorithms used for specific
types of data sources. To add an algorithm to your project, however, you need only provide the
name; internally, GO will use the correct algorithms for the data sources available to you.
Please contact the Orbital Insight Client Success Team ([email protected]) for further
information about exactly what algorithms are available with your account.

The body of your POST contains only a list of the algorithm name(s):

{
    "algorithm_ids": [
        "CAR_DETECTOR_ANALYSIS"
    ]
}

The HTTP operation is:

POST /projects/$P/versions/$V/algorithms

and it should return a result like this:

{
  "data": [
    {
      "algorithm_id": "CAR_DETECTOR_ANALYSIS",
      "algorithm_metadata": null
    }
  ],
  "list_attributes": {
    "limit": 1,
    "offset": 0,
    "total": 1
  },
  "status": 201
}

The fields should be self-explanatory.

If you perform a GET on the endpoint /projects/$P/versions/$V/algorithms, you will see that
the algorithm has been added.

Other Project Parameters

In order to execute, a project needs to have one or more AOIs and one or more algorithms set. You
can also set the time range over which the algorithm will be run and the amount of cloud cover
you are willing to accept in the source imagery. This can be done either when creating a Version
resource via the POST body, or by updating an existing Version resource via the PUT body:

{
    "start_date": "2017-01-01 00:00:00",
    "end_date": "2017-06-30 00:00:00",
    "cloud_cover": "0.2"
}

The dates are given in UTC. The cloud cover is a number between 0.0 and 1.0, indicating the maximum
amount of cloud cover you are willing to tolerate: ten percent (0.10) to twenty percent (0.20) is
typically acceptable.

Updated about 3 years ago