diff --git a/docs/overview/images/qgis-plugin-add-layer-from-stac.png b/docs/overview/images/qgis-plugin-add-layer-from-stac.png new file mode 100644 index 00000000..9e7e3560 Binary files /dev/null and b/docs/overview/images/qgis-plugin-add-layer-from-stac.png differ diff --git a/docs/overview/images/qgis-plugin-add-layer.png b/docs/overview/images/qgis-plugin-add-layer.png new file mode 100644 index 00000000..3c7562d6 Binary files /dev/null and b/docs/overview/images/qgis-plugin-add-layer.png differ diff --git a/docs/overview/images/qgis-plugin-apply-rendering.png b/docs/overview/images/qgis-plugin-apply-rendering.png new file mode 100644 index 00000000..88534c1d Binary files /dev/null and b/docs/overview/images/qgis-plugin-apply-rendering.png differ diff --git a/docs/overview/images/qgis-plugin-band-calc.png b/docs/overview/images/qgis-plugin-band-calc.png new file mode 100644 index 00000000..c735f9d2 Binary files /dev/null and b/docs/overview/images/qgis-plugin-band-calc.png differ diff --git a/docs/overview/images/qgis-plugin-establish-connection.png b/docs/overview/images/qgis-plugin-establish-connection.png new file mode 100644 index 00000000..9f73dd7f Binary files /dev/null and b/docs/overview/images/qgis-plugin-establish-connection.png differ diff --git a/docs/overview/images/qgis-plugin-final.png b/docs/overview/images/qgis-plugin-final.png new file mode 100644 index 00000000..88c9a534 Binary files /dev/null and b/docs/overview/images/qgis-plugin-final.png differ diff --git a/docs/overview/images/qgis-plugin-find-open-pc.png b/docs/overview/images/qgis-plugin-find-open-pc.png new file mode 100644 index 00000000..39375e3a Binary files /dev/null and b/docs/overview/images/qgis-plugin-find-open-pc.png differ diff --git a/docs/overview/images/qgis-plugin-find-raster-calculator.png b/docs/overview/images/qgis-plugin-find-raster-calculator.png new file mode 100644 index 00000000..0f0a3581 Binary files /dev/null and b/docs/overview/images/qgis-plugin-find-raster-calculator.png differ diff --git a/docs/overview/images/qgis-plugin-find-symbology.png b/docs/overview/images/qgis-plugin-find-symbology.png new file mode 100644 index 00000000..b1dfd0ee Binary files /dev/null and b/docs/overview/images/qgis-plugin-find-symbology.png differ diff --git a/docs/overview/images/qgis-plugin-input-layers.png b/docs/overview/images/qgis-plugin-input-layers.png new file mode 100644 index 00000000..bd8795c5 Binary files /dev/null and b/docs/overview/images/qgis-plugin-input-layers.png differ diff --git a/docs/overview/images/qgis-plugin-layer-properties.png b/docs/overview/images/qgis-plugin-layer-properties.png new file mode 100644 index 00000000..e5928d33 Binary files /dev/null and b/docs/overview/images/qgis-plugin-layer-properties.png differ diff --git a/docs/overview/images/qgis-plugin-layers-panel.png b/docs/overview/images/qgis-plugin-layers-panel.png new file mode 100644 index 00000000..be279660 Binary files /dev/null and b/docs/overview/images/qgis-plugin-layers-panel.png differ diff --git a/docs/overview/images/qgis-plugin-new-stac-connection.png b/docs/overview/images/qgis-plugin-new-stac-connection.png new file mode 100644 index 00000000..c10610c6 Binary files /dev/null and b/docs/overview/images/qgis-plugin-new-stac-connection.png differ diff --git a/docs/overview/images/qgis-plugin-pc-pro.png b/docs/overview/images/qgis-plugin-pc-pro.png new file mode 100644 index 00000000..d152f2e0 Binary files /dev/null and b/docs/overview/images/qgis-plugin-pc-pro.png differ diff --git a/docs/overview/images/qgis-plugin-raster-calculator.png b/docs/overview/images/qgis-plugin-raster-calculator.png new file mode 100644 index 00000000..9d92e3ad Binary files /dev/null and b/docs/overview/images/qgis-plugin-raster-calculator.png differ diff --git a/docs/overview/images/qgis-plugin-select-bands.png b/docs/overview/images/qgis-plugin-select-bands.png new file mode 100644 index 00000000..9e55b1c7 Binary files /dev/null and b/docs/overview/images/qgis-plugin-select-bands.png differ diff --git a/docs/overview/images/qgis-plugin-select-colormap.png b/docs/overview/images/qgis-plugin-select-colormap.png new file mode 100644 index 00000000..db1dbd23 Binary files /dev/null and b/docs/overview/images/qgis-plugin-select-colormap.png differ diff --git a/docs/overview/images/qgis-plugin-select-open-pc.png b/docs/overview/images/qgis-plugin-select-open-pc.png new file mode 100644 index 00000000..61e61262 Binary files /dev/null and b/docs/overview/images/qgis-plugin-select-open-pc.png differ diff --git a/docs/overview/images/qgis-plugin-select-pc.png b/docs/overview/images/qgis-plugin-select-pc.png new file mode 100644 index 00000000..e9bbd895 Binary files /dev/null and b/docs/overview/images/qgis-plugin-select-pc.png differ diff --git a/docs/overview/images/qgis-plugin-select-sentinel-2.png b/docs/overview/images/qgis-plugin-select-sentinel-2.png new file mode 100644 index 00000000..53fd763d Binary files /dev/null and b/docs/overview/images/qgis-plugin-select-sentinel-2.png differ diff --git a/docs/overview/images/qgis-plugin-show-footprints.png b/docs/overview/images/qgis-plugin-show-footprints.png new file mode 100644 index 00000000..b3965080 Binary files /dev/null and b/docs/overview/images/qgis-plugin-show-footprints.png differ diff --git a/docs/overview/images/qgis-plugin.png b/docs/overview/images/qgis-plugin.png deleted file mode 100644 index 551c5939..00000000 Binary files a/docs/overview/images/qgis-plugin.png and /dev/null differ diff --git a/docs/overview/images/qgis-working-with.png b/docs/overview/images/qgis-working-with.png deleted file mode 100644 index ab7032f6..00000000 Binary files a/docs/overview/images/qgis-working-with.png and /dev/null differ diff --git a/docs/overview/qgis-plugin-open-pc.md b/docs/overview/qgis-plugin-open-pc.md new file mode 100644 index 00000000..956ea28f --- /dev/null +++ b/docs/overview/qgis-plugin-open-pc.md @@ -0,0 +1,186 @@ +# Accessing Planetary Computer data in QGIS + +[QGIS][qgis-home] is a popular open-source desktop GIS application used for +mapping, analysis, and visualization of spatial data. While much of the +Planetary Computer is designed to support [cloud-native][cnative] workflows, +it's easy to use our data in a traditional desktop clients, like QGIS, as well. + +## Native STAC browser in QGIS + +Since the Open Planetary Computer metadata API is built on the [STAC](https://stacspec.org/) standard, the easiest way to search for and add data to QGIS is by using the native STAC browser within QGIS. This is fully supported from [QGIS 4.0.0](https://qgis.org/download/) onward. + +A STAC catalog in QGIS is a browsable data source. It exposes hierarchical STAC metadata (catalog → collection → item → asset) instead of a single static file. When you expand nodes, QGIS issues live API requests to the Open Planetary Computer STAC endpoint so you always see the latest collections and items available. + +### Create the STAC connection + +Create the STAC connection inside QGIS by following these steps: + +1. Locate STAC in the Browser panel on the left side of the screen. +2. Right-click STAC and select New STAC Connection to open the configuration dialog. +```{image} images/qgis-plugin-new-stac-connection.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` + +### Configure STAC connection + +1. In the "Name" field, name this connection. For example, “Microsoft Open Planetary Computer” +2. Enter the URL for Open Planetary Computer: https://planetarycomputer.microsoft.com/api/stac/v1 +3. Before creating the connection, you must enter an authentication configuration. If you do not see Open Planetary Computer in the list of options, click the plus (+) icon to add a new authentication. +```{image} images/qgis-plugin-establish-connection.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +4. In the resulting screen, enter a name for the authentication connection. +5. In the dropdown, select Microsoft Planetary Computer +```{image} images/qgis-plugin-select-pc.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +6. By default Open Planetary Computer should be selected. If for whatever reason it is not, switch from Planetary Computer Pro to Open Planetary Computer. (If you would like to set up a Planetary Computer Pro connection, see the tutorial [here](https://learn.microsoft.com/en-us/azure/planetary-computer/configure-qgis).) +```{image} images/pc-pro.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +7. Click Save to create the new authentication. + +Once these settings are complete, click OK to create the STAC connection. + +## Using the QGIS STAC connection + +To browse the collections, expand your STAC connection in the data layer browser. You will see many collections to choose from. Continue to expand the collections until you locate a STAC Item. To visualize this item, select the item and drag it to the map view. If the data is a Cloud Optimized GeoTIFF (COG) or Cloud Optimized Point Cloud (COPC), it automatically imports and projects onto the map. + +```{image} images/find-open-pc.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` + +### STAC search and filtering + +To more effectively search for data or run a STAC filter in your catalog, the STAC API is exposed through the Layer manager. + +1. On the Layer menu, select Add Layer > Add Layer from STAC Catalog. +```{image} images/add-layer-from-stac.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +2. If necessary, select your Open Planetary Computer STAC connection, and click Connect. +```{image} images/select-open-pc.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +3. You will need to choose a filter to be able to STAC items. Click Filters and narrow down to a spatial selection, temporal selection, or specific collection. +```{image} images/select-sentinel-2.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +4. With “Show Footprints” selected you can see the area covered by a specific STAC item before adding it to your canvas. +```{image} images/qgis-plugin-show-footprints.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +5. Select an item that matches your needs and click “Add.” Alternatively, add specific layers by right clicking on the STAC item and selecting “Add Layer.” +```{image} images/qgis-plugin-add-layer.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` + +Depending on your selection, you will now see the layers available in your Layers panel. + +```{image} images/qgis-plugin-layers-panel.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` + +## Using Open Planetary Computer data + +Streaming raster imagery through the Open Planetary Computer makes raster calculations easier to perform. + +### Generating an NDVI calculation virtually + +Follow the steps below to quickly generate an NDVI calculation using the same Sentinel-2A imagery from above. + +1. Open the Processing Toolbox using Ctrl+Alt+T (Ctrl+Shift+T on Mac) or by accessing Processing > Toolbox from the toolbar. +2. In the Processing Toolbox, expand the Raster analysis options and locate the Raster calculator (virtual). We are able to use this virtual calculator because of our STAC connection, none of these layers are downloaded to your computer at this point. +```{image} images/qgis-plugin-find-raster-calculator.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +3. In the resulting dialog box, click on the ellipses under “Input layers” to select the necessary inputs. +```{image} images/qgis-plugin-input-layers.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +4. For an NDVI calculation, we will need Band 4 and Band 8. For other calculations, you might need different bands. Select the necessary bands and select “OK.” +```{image} images/qgis-plugin-select-bands.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +5. To enter in the NDVI calculation, you can copy the formula into the Expression box or open up the Expression editor to input it manually. +```{image} images/qgis-plugin-raster-calculator.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +6. To input manually, double click on a layer to add it to the expression, and click on the appropriate operators to build a formula. +```{image} images/qgis-plugin-band-calc.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +7. Provide a layer name and click “Run.” +8. QGIS will calculate the NDVI layer virtually, without needing to download the imagery. This improves speed and reduces the load on your computer. The resulting image will likely be a gray-scale, with min/max values somewhere between -1 and +1. To edit the colormap, right click on the layer name and select “Properties.” +```{image} images/qgis-plugin-layer-properties.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +9. Navigate to the Symbology tab and select a Render type of “Singleband pseudocolor.” +```{image} images/qgis-plugin-find-symbology.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +10. If it’s not already selected, select the RdYlGn colormap. This is standard for NDVI. +```{image} images/qgis-plugin-select-colormap.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` +11. Finally, adjust the min/max values to be -1 and +1 and click Apply. The map layer should quickly re-render with the new colormap and values. +```{image} images/qgis-plugin-apply-rendering.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` + +You can use the Identify Features (Ctrl+Shift+i) tool within QGIS to verify that the values are as expected. + +```{image} images/qgis-plugin-final.png +:height: 500 +:name: Working with data in QGIS +:class: no-scaled-link +``` + +[qgis-home]: https://qgis.org/en/site/about/index.html +[cnative]: https://en.wikipedia.org/wiki/Cloud_native_computing +[plugin-url]: https://stac-utils.github.io/qgis-stac-plugin/ +[kartoza]: https://kartoza.com/ +[user-guide]: https://stac-utils.github.io/qgis-stac-plugin/user-guide/ +[pc-catalog]: https://planetarycomputer.microsoft.com/catalog +[cql2]: https://github.com/radiantearth/stac-api-spec/tree/master/fragments/filter#example-1 +[stac-ql]: https://github.com/radiantearth/stac-api-spec/tree/master/fragments/query#stac-api---query-fragment diff --git a/docs/overview/qgis-plugin.md b/docs/overview/qgis-plugin.md deleted file mode 100644 index e8c15a12..00000000 --- a/docs/overview/qgis-plugin.md +++ /dev/null @@ -1,74 +0,0 @@ -# Accessing Planetary Computer data in QGIS - -[QGIS][qgis-home] is a popular open-source desktop GIS application used for -mapping, analysis, and visualization of spatial data. While much of the -Planetary Computer is designed to support [cloud-native][cnative] workflows, -it's easy to use our data in a traditional desktop clients, like QGIS, as well. - -## QGIS STAC API Plugin - -Since the Planetary Computer metadata API is built on the [STAC](https://stacspec.org/) standard, the easiest way -to search for and add data to QGIS is by using the [STAC API Browser plugin][plugin-url]. Microsoft -supported development of this plugin, with our partners [Kartoza][kartoza], to -make accessing STAC APIs from QGIS easier. - -For a general overview on plugin usage, the [official user guide][user-guide]. - -### Searching for data - -Launch the STAC Browser plugin from the Plugin menu or toolbar within the app. -Select the "Microsoft Planetary Computer STAC API" option from the pre-loaded -list of connections, then click "Fetch collections" to see the list of datasets -in the catalog. You can visit the [Planetary Computer Data Catalog][pc-catalog] -to see information about each dataset, including specific temporal and spatial -coverages. - -Select one or many collections in the list, and optionally restrict the search -using the filter by date or filter by extent options. If you want to additionally -filter on specific dataset attributes (e.g., cloud cover) you can use the Advanced filter -to add custom [CQL2][cql2] or [STAC-QL][stac-ql] filters. Click the search button to see -the results of your query. - -```{image} images/qgis-plugin.png -:height: 500 -:name: QGIS STAC API plugin -:class: no-scaled-link -``` - -The plugin also allows you to search data from other STAC API providers, and is -preloaded with a list of other popular catalogs. - -### Working with data - -Once you've identified dataset items of interest, you have three ways of interacting with them: - -1. _Add the item footprint to your QGIS workspace_. This adds a geojson shape -representing the data item extent on the map and includes all of its metadata -attributes. Use this option to quickly inspect the data without having to load -the full data asset. -2. _Add asset as layer_. You can also add the actual data asset, typically a -Cloud-Optimized GeoTIFF, directly to your QGIS workspace. This does not -download the asset locally, but rather efficiently fetches the overview layer -for your current zoom layer. -**Note that assets added added as COG layers are signed using the SAS token -mechanism, which expires by default after an hour.** You'll need to re-add the -layer, though we're working on improvements to that workflow in the next version -of the plugin. This option may be slower if you're working with a local QGIS instance. -3. _Download the asset_. The plugin also allows you to download the asset directly, so you can -work with the file itself. Be sure to set your download directory on the Settings tab to a path -located within your home directory, so the data is preserved between launches. - -```{image} images/qgis-working-with.png -:height: 500 -:name: Working with data in QGIS -:class: no-scaled-link -``` - -[qgis-home]: https://qgis.org/en/site/about/index.html -[cnative]: https://en.wikipedia.org/wiki/Cloud_native_computing -[plugin-url]: https://stac-utils.github.io/qgis-stac-plugin/ -[kartoza]: https://kartoza.com/ -[user-guide]: https://stac-utils.github.io/qgis-stac-plugin/user-guide/ -[pc-catalog]: https://planetarycomputer.microsoft.com/catalog -[cql2]: https://github.com/radiantearth/stac-api-spec/tree/master/fragments/filter#example-1 -[stac-ql]: https://github.com/radiantearth/stac-api-spec/tree/master/fragments/query#stac-api---query-fragment