Umbra Parameters
For more information about Umbra capabilities, see their product guide. Note that Umbra multilook options have been re-aligned by Vantor into a Dwell Duration parameter instead, as defined below.
Required fields are denoted by an asterisk.
Query parameters
| Query parameter | Description | Example |
|---|---|---|
validation_only | Validate a request before sending. | /tasking/umbra?validation_only=true |
General collection parameters
These parameters control the where and when of the collection.
| Parameter | Type | Description | Allowed Values | Example |
|---|---|---|---|---|
geometry* | object | The center point of the collection area | GeoJSON Point objects | See AOIs |
start_collect_datetime* | string | The date and time the requested imagery collection can start. | ISO-8601 Dates or now. Date and time can not be in the past. | "start_collect_datetime": "2026-05-01 18:34:57Z" |
end_collect_datetime* | string | ISO-8601 formatted The date and time the imagery collection request will expire. | The end date and time must occur at least ten minutes after start_collect_datetime and within 364 days of placing the request. | "end_collect_datetime": "2026-04-30 18:34:57Z" |
request_description | string | Optional description. | "request_description": "Albuquerque" |
Detailed collection parameters
The tasking_details object controls more specific collection parameters.
| Parameter | Type | Description | Allowed Values | Default Value | Example |
|---|---|---|---|---|---|
range_resolution_meters* | number | The requested ground-projected resolution in meters for the collection.¹ | 0.25, 0.35, 0.5, 1.0 | N/A | "range_resolution_meters": 0.35 |
dwell_duration | string | Describes the length of collection time. See Dwell. | single-look, medium-dwell, long-dwell | medium-dwell | "dwell_duration"; "single-look" |
polarization | string | Polarization of the radar signal. See Polarization. | VV, HH | VV | "polarization": "HH" |
min_graze_angle | number | Minimum graze angle. See Graze angle | varies | varies | "min_graze_angle": 30 |
max_graze_angle | number | Maximum graze angle. See Graze angle | varies | varies | "max_graze_angle": 60 |
min_target_azimuth_angle | number | Minimum target azimuth angle. See Azimuth angle | 0-360 (inclusive) | 0 | "min_target_azimuth_angle": 90 |
max_target_azimuth_angle | number | Maximum target azimuth angle. See Azimuth angle | 0-360 (inclusive) | 360 | "max_target_azimuth_angle": 180 |
imaging_mode | string | Included for future compatibility. | SAR Spotlight | SAR Spotlight | "imaging_mode": "SAR Spotlight" |
1: More formally known as the Ground Range Impulse Response (IPR) of the SAR data.
Product parameters
The product_details object contains specifications related to the delivered products.
| Parameter | Type | Description | Allowed Values | Default Value | Example |
|---|---|---|---|---|---|
product_output* | array of strings | The type of SAR image; a combination of projection and processing level. See Product outputs | [DI, CSI,SLC] | [] | "product_output": ["DI", "CSI"] |
file_format | string | File format for DI and CSI outputs. See Product outputs for more information on SAR NITF formats. | SAR NITF, GeoTIFF | GeoTIFF | "file_format": "SAR NITF" |
licensing* | object | Licensing details | |||
licensing.end_use_code* | string | This is the intended use of the ordered imagery. | See End use codes | N/A | "end_use_code": "AGR" |
Configuring output locations
Outputs can be specified using the same options as used by the Ordering API.
| Parameter | Type | Description |
|---|---|---|
output_configs | array | Sets the location(s) for delivering collected imagery. |
See Ordering Output Delivery Options in the Ordering section.
Path variables
To insert the Tasking ID automatically into an output path, use the $.tasking_id variable.
{
"type": "amazon_s3",
"bucket": "my-tasking-bucket",
"prefix": "deliveries/$.tasking_id"
}
Notifications
| Parameter | Type | Description |
|---|---|---|
notifications | array | Sets targets to be notified when the status of the request is updated. |
See Tasking notifications for options
Date and time formats
The collection time frame is determined by the start date and the end date. Both are required.
The end date must be later than the start date and both must be in the future.
"start_datetime": "2025-01-01T00:00:00Z",
"end_datetime": "2025-03-01T00:00:00Z",
Dates must use ISO 8601 standards and must specify a time zone designator of either UTC or an offset from UTC.
The following are all valid datetime formats.
"2024-04-02T00:00Z"
"2024-04-02T00:00:00Z"
"20240402T00:00+0000"
"2024-04-02T4:00+04:00"
"2024-04-02T04:00+04:00"
"2024-04-01T22:00-02"
Umbra tasking can also accept a start_collect_datetime of now to start the collection window immediately.
AOIs
Imaging location must be submitted as a GeoJSON Point. GeoJSON Features are not accepted. A 5x5 km image footprint containing this point will be delivered. The orientation of this footprint will vary with the actual collection geometry.
GeoJSON Points use X,Y coordinate order, not latitude,longitude order.
Polarization
Polarization is the orientation of the SAR signal’s electric field with respect to the earth. The SAR satellites used by Vantor provide single polarization image collection, which means that the received SAR signal is only sampled in the same electric field orientation as the transmitted signal. The polarization orientations supported are VV (vertically polarized with respect to the earth) and HH (horizontally polarized with respect to the earth).
Dwell
Vantor uses ‘dwell’ terminology to configure the azimuth axis resolution of the complex image. The longer the dwell, the finer the native azimuth resolution and the longer the imaging duration. Single-look orders will be tasked with a single “look” and an azimuth resolution equal to the ordered range resolution. For medium-dwell and long-dwell collections, SLC data will have a finer resolution in the azimuth axis (pixels will be asymmetric), while DI & CSI data are ‘multilooked’ to an approximately square resolution and pixel. This multilooking process reduces the amount of speckle (the visual ‘noisiness’ look of SAR imagery), resulting in a ‘better-looking’ image for exploitation purposes. Single-look modes will have the highest speckle and have the highest collection density per pass; Long Dwell modes have the most speckle mitigation due to multi-looking, but fewer targets can be collected per pass due to the longer imaging time.
The relationship of dwell duration to number of looks, collection duration, and output image resolution is detailed in the following tables:
Single-look Dwell
| Ground Range Resolution (IPR) (m) | Multi-look factor* | Approx. collection duration** | Native Azimuth IPR* (m) | SLC IPR* (ground range x azimuth) | DI/CSI IPR* (ground range x azimuth) |
|---|---|---|---|---|---|
| 1.0 | 1 | ~2s | 1.0 | 1 x 1m | 1 x 1 m |
| 0.50 | 1 | ~3s | 0.50 | 50 x 50 cm | 50 x 50 cm |
| 0.35 | 1 | ~5s | 0.35 | 35 x 35 cm | 35 x 35 cm |
| 0.25 | 1 | ~6s | 0.25 | 25 x 25 cm | 25 x 25 cm |
Medium Dwell
| Ground Range Resolution (IPR) (m) | Multi-look factor* | Approx. collection duration** | Native Azimuth IPR* (m) | SLC IPR* (ground range x azimuth) | DI/CSI IPR* (ground range x azimuth) |
|---|---|---|---|---|---|
| 1.0 | 8 | ~12s | 0.125 | 1 m x 12.5 cm | 1 x 1m |
| 0.50 | 4 | ~12s | 0.125 | 50 x 12.5 cm | 50 x 50 cm |
| 0.35 | 3 | ~12s | 0.117 | 35 x 11.7 cm | 35 x 35 cm |
| 0.25 | 2 | ~12s | 0.125 | 25 x 12.5 cm | 25 x 25 cm |
Long Dwell
| Ground Range Resolution (IPR) (m) | Multi-look factor* | Approx. collection duration** | Native Azimuth IPR* (m) | SLC IPR* (ground range x azimuth) | DI/CSI IPR* (ground range x azimuth) |
|---|---|---|---|---|---|
| 0.50 | 8 | ~25s | 0.063 | 50 x 6 cm | 50 x 50 cm |
| 0.35 | 5 | ~25s | 0.070 | 35 x 7 cm | 35 x 35 cm |
| 0.25 | 3 | ~20s | 0.083 | 25 x 8.3 cm | 25 x 25 cm |
* Resolutions and multi-look factors are approximate; actual image resolution as-collected can vary up to 30%.
** Actual collection duration will vary with collection geometry.
Output image pixel spacing will be finer than the above specified resolution by a factor of 1.2-1.5 due to IPR oversampling.
Restrictions
The long-dwell duration cannot be combined with a resolution of 1.0 meter.
The CSI product option is not available with single-look dwell durations and will fail validation.
Graze Angle
Graze angle is the angle between the line-of-sight ray and the tangent to the ground. Like off-nadir angle, it describes how "sideways" the sensor is looking at the ground.
Vantor has established default Graze angle ranges based on resolution to best balance signal to noise ratio, layover, and access opportunities. The defaults are provided in the table below.
If needed, graze angle can be optionally set, with min_graze_angle being at least 10 degrees and max_graze_angle being between 60 and 80 degrees (depending on resolution; see the third column in table below). The absolute difference between minimum and maximum must greater than or equal to 1 degree.
Graze angles lower than these defaults may have poor signal to noise ratio, and graze angles above these defaults may have excessive layover effects for certain targets. We suggest only advanced SAR users modify these values.
| Resolution | Graze Angle - Default Range | Graze Angle – Max Allowed |
|---|---|---|
| 0.25m | 50° - 60° | 60° |
| 0.35m | 45° - 70° | 70° |
| 0.5m | 40° - 70° | 75° |
| 1.0m | 30° - 70° | 80° |
Some users may be more familiar with incidence angle for SAR, which is the complement of graze angle: graze angle = 90 – incidence angle.
Azimuth Angle
Target azimuth is the compass direction measured from the target center point to the satellite. This angle is measured from north in clockwise degrees. Target Azimuth can be thought of as the compass direction a person is facing if they are standing at the target center point and facing the satellite during the collection.
Users have the ability to prescribe specific target azimuth constraints from 0–360°. However, it is important to note that SAR imagery collection is not possible at nadir or along the satellite’s ground track. As such, northernly (~325°-35°) and southernly (~145°-215°) collection azimuths are not generally feasible over most of the globe with the SAR satellites currently available. Setting target azimuth constraints in these ranges may result in no collection feasibility.
If min_target_azimuth and/or max_target_azimuth are provided, the absolute difference must be greater than or equal to 1 degree.
Product Outputs
You must specify one or more of the following product output image types to deliver:
DI: Detected Image; Ground Range Detected Image- A single-band grayscale image of SAR magnitude data, projected to a ground plane. Multilook processed as applicable. If ordered in NITF format, -NITF format image adheres to the NGA SIDD specification.
CSI: Color Subaperture Image: Optionally available only in Medium Dell and Long Dwell collection modes.- A three-band RGB image of SAR magnitude data, projected to a ground plane. Multilook processed as applicable. The bands are colorized by when during the collection the data was received – red for earlier in the collection, blue for late in the collection. Manmade objects are often more reflective back towards the SAR sensor at specific orientations or azimuths, which results in colorization of that object. Natural objects are generally diffuse reflectors, and will generally still appear grayscale.␍
- NITF format image adheres to the NGA SIDD specification.
SLC: Single-Look Complex Image: Only delivered in NITF format.- A two-band image in the native sensor-to-ground slant plane. Generally asymmetric resolution (different in each image axis). The two bands represent magnitude and phase information, but are formed in complex I & J planes.
- NITF format image adheres to the NGA SICD specification.
Modifying the end date of an Umbra tasking request
Umbra tasking orders cannot be modified.
Canceling an Umbra request
Umbra requests can only be canceled before reaching a COLLECTING status See Cancel a Tasking request and Tasking Status.