feat: STAC Render Extension support #1038

alekzvik · 2024-11-26T13:06:44Z

What I am changing

Adding support of STAC render extension to titiler. This is a continuation of work started at satsummit stac sprint.

How I did it

Adding two endpoints:
- /renders/ lists all renders
- /renders/<render_id> returns a specific render with its metadata and template links to tilejson.json and WMTS

How you can test it

Go to swaggerUI and use some of the examples from the stac extension repo. If you click on "raw" button, it will generate a link you can use directly, e.g. https://raw.githubusercontent.com/stac-extensions/render/65edf9bcc7dfe0a02e0191a277c1ac81d86b698e/examples/item-landsat8.json

Related Issues

Continuation of Render Extension #1034
Closes add support for the STAC Render extension #974

Example responses

Those are generated based on this STAC item
Request: http://127.0.0.1:8000/stac/renders/sir?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json
Response:

{
  "params": {
    "assets": [
      "B12",
      "B08",
      "B04"
    ],
    "title": "Shortwave Infra-red",
    "rescale": [
      [
        0,
        5000
      ],
      [
        0,
        7000
      ],
      [
        0,
        9000
      ]
    ],
    "resampling": "nearest"
  },
  "links": [
    {
      "href": "http://127.0.0.1:8000/stac/renders/sir?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json",
      "rel": "self",
      "type": "application/json",
      "title": "sir render item"
    },
    {
      "href": "http://127.0.0.1:8000/stac/{tileMatrixSetId}/tilejson.json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json&assets=B12&assets=B08&assets=B04&resampling_method=nearest",
      "rel": "tilesets-map",
      "templated": true,
      "title": "tilejson file for sir"
    },
    {
      "href": "http://127.0.0.1:8000/stac/{tileMatrixSetId}/WMTSCapabilities.xml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json&assets=B12&assets=B08&assets=B04&resampling_method=nearest",
      "rel": "tilesets-map",
      "templated": true,
      "title": "WMTS service for sir"
    }
  ]
}

Request: http://127.0.0.1:8000/stac/renders?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json
Response:

{
  "renders": {
    "sir": {
      "params": {
        "assets": [
          "B12",
          "B08",
          "B04"
        ],
        "title": "Shortwave Infra-red",
        "rescale": [
          [
            0,
            5000
          ],
          [
            0,
            7000
          ],
          [
            0,
            9000
          ]
        ],
        "resampling": "nearest"
      },
      "links": [
        {
          "href": "http://127.0.0.1:8000/stac/renders/sir?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json",
          "rel": "self",
          "type": "application/json",
          "title": "sir render item"
        },
        {
          "href": "http://127.0.0.1:8000/stac/{tileMatrixSetId}/tilejson.json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json&assets=B12&assets=B08&assets=B04&resampling_method=nearest",
          "rel": "tilesets-map",
          "templated": true,
          "title": "tilejson file for sir"
        },
        {
          "href": "http://127.0.0.1:8000/stac/{tileMatrixSetId}/WMTSCapabilities.xml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json&assets=B12&assets=B08&assets=B04&resampling_method=nearest",
          "rel": "tilesets-map",
          "templated": true,
          "title": "WMTS service for sir"
        }
      ]
    }
  },
  "links": [
    {
      "href": "http://127.0.0.1:8000/stac/renders?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json",
      "rel": "self",
      "type": "application/json",
      "title": "List Render Items"
    }
  ]
}

Render extension started during STAC render sprint in SatSummit Lisbon 2024. - listing (or showing to please Vincent) Please contribute to complete the feature to - generate the final XYZ link for rendering following the rules in STAC extensions - add a dedicated endpoint for render XYZ

vincentsarago · 2024-11-26T13:10:20Z

src/titiler/application/titiler/application/main.py

@@ -122,6 +123,7 @@ def validate_access_token(access_token: str = Security(api_key_query)):
        router_prefix="/stac",
        extensions=[
            stacViewerExtension(),
+            renderExtension(),


I think we should rename it stacRenderExtension

I submitted it 3 minutes ago, how are you so fast? 🙃

Makes perfect sense, I will rename it

src/titiler/extensions/titiler/extensions/render.py

vincentsarago · 2024-11-26T13:13:27Z

src/titiler/extensions/titiler/extensions/render.py

+    color_formula: Optional[str] = None
+    resampling: Optional[str] = None
+    expression: Optional[str] = None
+    minmax_zoom: Optional[Annotated[List[int], 2]] = None


I think you might want to allow more keys event if they are not supported directly by titiler

I took the list of keys from the extension specification here: https://github.com/stac-extensions/render/tree/65edf9bcc7dfe0a02e0191a277c1ac81d86b698e?tab=readme-ov-file#render-object

We can allow the model to validate clearly defined fields but allow extra fields to be read from the render object in STAC and returned by the endpoint. This way we are not overly restrictive but still maintain a defined standard. What do you think?

vincentsarago · 2024-11-26T13:20:07Z

src/titiler/extensions/titiler/extensions/render.py

+            with factory.reader(src_path) as src:
+                renders = src.item.properties.get("renders", {})
+            pprint(renders)
+            return renders


I would maybe return a response in form of

{ "{renderId}": { "params": {render info}, "links": [ { "rel": "self", "title": "{renderId}", "type": "application/json", "templated": true, "href": "/renders/{renderId} href" }, { "title": "{renderId} tilejson", "type": "application/json", "templated": true, "href": "titiler tilejson href" }, { "title": "{renderId} wmtsa", "type": "application/json", "templated": true, "href": "titiler wmts href" }, ] }, "links": [ { "rel": "self", "type": "application/json", "href": "https://titiler.api/renders" }, ], }

alekzvik · 2024-11-26T16:39:35Z

Latest changes:

fix typing import that did not work on python 3.8
rename renderExtention -> stacRenderExtension
new response structure, examples below

Both are based on item-steninel2.json
Request: http://127.0.0.1:8000/stac/renders/sir?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json
Response:

{
  "params": {
    "assets": [
      "B12",
      "B08",
      "B04"
    ],
    "title": "Shortwave Infra-red",
    "rescale": [
      [
        0,
        5000
      ],
      [
        0,
        7000
      ],
      [
        0,
        9000
      ]
    ],
    "resampling": "nearest"
  },
  "links": [
    {
      "href": "http://127.0.0.1:8000/stac/renders/sir?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json",
      "rel": "self",
      "type": "application/json",
      "title": "sir render item"
    },
    {
      "href": "http://127.0.0.1:8000/stac/{tileMatrixSetId}/tilejson.json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json&assets=B12&assets=B08&assets=B04&resampling_method=nearest",
      "rel": "tilesets-map",
      "templated": true,
      "title": "tilejson file for sir"
    },
    {
      "href": "http://127.0.0.1:8000/stac/{tileMatrixSetId}/WMTSCapabilities.xml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json&assets=B12&assets=B08&assets=B04&resampling_method=nearest",
      "rel": "tilesets-map",
      "templated": true,
      "title": "WMTS service for sir"
    }
  ]
}

Request: http://127.0.0.1:8000/stac/renders?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json
Response:

{
  "renders": {
    "sir": {
      "params": {
        "assets": [
          "B12",
          "B08",
          "B04"
        ],
        "title": "Shortwave Infra-red",
        "rescale": [
          [
            0,
            5000
          ],
          [
            0,
            7000
          ],
          [
            0,
            9000
          ]
        ],
        "resampling": "nearest"
      },
      "links": [
        {
          "href": "http://127.0.0.1:8000/stac/renders/sir?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json",
          "rel": "self",
          "type": "application/json",
          "title": "sir render item"
        },
        {
          "href": "http://127.0.0.1:8000/stac/{tileMatrixSetId}/tilejson.json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json&assets=B12&assets=B08&assets=B04&resampling_method=nearest",
          "rel": "tilesets-map",
          "templated": true,
          "title": "tilejson file for sir"
        },
        {
          "href": "http://127.0.0.1:8000/stac/{tileMatrixSetId}/WMTSCapabilities.xml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json&assets=B12&assets=B08&assets=B04&resampling_method=nearest",
          "rel": "tilesets-map",
          "templated": true,
          "title": "WMTS service for sir"
        }
      ]
    }
  },
  "links": [
    {
      "href": "http://127.0.0.1:8000/stac/renders?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstac-extensions%2Frender%2F65edf9bcc7dfe0a02e0191a277c1ac81d86b698e%2Fexamples%2Fitem-sentinel2.json",
      "rel": "self",
      "type": "application/json",
      "title": "List Render Items"
    }
  ]
}

For the /renders/ endpoint, I have not yet figured out how to deal with the response model and put renders in additional field renders.

emmanuelmathot and others added 3 commits November 19, 2024 17:45

feat(stac): add render extenstions support

e20dfef

remove unnecessary item.json file

c63a482

vincentsarago reviewed Nov 26, 2024

View reviewed changes

src/titiler/extensions/titiler/extensions/render.py Outdated Show resolved Hide resolved

vincentsarago reviewed Nov 26, 2024

View reviewed changes

alekzvik added 2 commits November 26, 2024 17:32

Rework the response structure to include links.

3f10def

rename renderExtension -> stacRenderExtension

9904786

alekzvik added 2 commits November 26, 2024 19:02

add tests for stacRenderExtension

a7121b2

add test for extra param

3e9995e

alekzvik changed the title ~~WIP: stac render extension support~~ feat: STAC Render Extension support Nov 26, 2024

alekzvik marked this pull request as ready for review November 26, 2024 18:31

alekzvik added 2 commits November 26, 2024 19:41

docs and docstrings

767c31d

fix typing in python 3.8

46b13ee

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: STAC Render Extension support #1038

feat: STAC Render Extension support #1038

alekzvik commented Nov 26, 2024 •

edited

Loading

vincentsarago Nov 26, 2024

alekzvik Nov 26, 2024

vincentsarago Nov 26, 2024

alekzvik Nov 26, 2024

vincentsarago Nov 26, 2024

alekzvik commented Nov 26, 2024 •

edited

Loading

feat: STAC Render Extension support #1038

Are you sure you want to change the base?

feat: STAC Render Extension support #1038

Conversation

alekzvik commented Nov 26, 2024 • edited Loading

What I am changing

How I did it

How you can test it

Related Issues

Example responses

vincentsarago Nov 26, 2024

Choose a reason for hiding this comment

alekzvik Nov 26, 2024

Choose a reason for hiding this comment

vincentsarago Nov 26, 2024

Choose a reason for hiding this comment

alekzvik Nov 26, 2024

Choose a reason for hiding this comment

vincentsarago Nov 26, 2024

Choose a reason for hiding this comment

alekzvik commented Nov 26, 2024 • edited Loading

alekzvik commented Nov 26, 2024 •

edited

Loading

alekzvik commented Nov 26, 2024 •

edited

Loading