developmentseed / developmentseed/titiler-covjson
Temporal endpoint surface (umbrella): enumerate and sequence the temporal slices
- Dominant language
- Python
- Stars
- 1
- Forks
- 1
- Avg merge
- 2d 1h
- Merged PRs (30d)
- 12
Description
Umbrella issue to track the full scope of the **Temporal endpoint surface** so no slice is dropped. The roadmap-realignment audit found the temporal surface was under-filed: only PointSeries (#18) and the upstream datetime-coercion tracker (#15) existed, though several temporal verbs are intended (Story 9 and the EDR query verbs).
## The temporal CoverageJSON verbs (each needs a real `t`)
- **Temporal `/position` -> PointSeries** -- #18 (already filed; needs the resolver-seam backing below).
- **Temporal `/area` -> PolygonSeries** -- not filed.
- **Temporal `/bbox` -> the EDR `cube` verb** (bbox + `z` + `datetime`) -- not filed; deferred in ADR-0001 until a real z/t axis backs it. Note that the verb carries **two** extra axes, and they need different backings: the `datetime` half comes from the resolver seam below (STAC item datetimes), while the `z` half needs a *level-dimensioned* source (a NetCDF/Zarr via xarray), which that seam does not provide on its own. A `/cube` slice scoped to `datetime` alone would ship the verb half-honored, which is what ADR-0001 rejected.
- **`/trajectory` -> Trajectory** -- #57. Note: `/trajectory` can source `t` from request-supplied per-vertex timestamps, so it does **not** require the dataset-temporal backing; the others do.
- **`/timeseries` across a STAC collection** (Story 9) -- not filed.
## Dependency
All of these except request-time `/trajectory` need a real dataset `t` source, which is the **STAC/Mosaic resolver seam** (#69) -- this umbrella depends on it. Also tracks #15 (upstream reduced-precision datetime coercion).
## The vertical (`z`) axis
Tracked here rather than under an umbrella of its own: it amounts to one verb (the `z` half of `/cube` above) and is deferred by the same ADR-0001 decision, so a separate issue would restate #69's blocker and that ADR's rationale a third time.
[ADR-0001](https://github.com/developmentseed/titiler-covjson/blob/main/docs/adr/0001-covjson-http-api-direction.md) records *why* a vertical coordinate is refused: "Ship `/cube` with `z`/`datetime` as no-op parameters" appears under Alternatives considered, rejected as dishonest, because the backing is a single 2-D raster with no vertical dimension to sample. What is recorded nowhere is the **blast radius**: three sites enforce that refusal independently, agree only by convention, and must relax together when a level-dimensioned backing lands.
- [`reject_vertical_selection`](https://github.com/developmentseed/titiler-covjson/blob/main/src/titiler_covjson/dependencies.py) -- rejects a `?z=` query parameter on `/position` and `/area`.
- [`parse_point_wkt`, `parse_multipoint_wkt`, `parse_polygon_wkt`](https://github.com/developmentseed/titiler-covjson/blob/main/src/titiler_covjson/wkt.py) -- reject a `Z` / `M` / `ZM` tag and a 3- or 4-token coordinate. (`M`, a linear-referencing measure, is out of scope rather than deferred: it has no meaning for raster sampling at all.)
- [`MultiPoint`](https://github.com/developmentseed/titiler-covjson/blob/main/src/titiler_covjson/geometry.py) -- stores bare `(x, y)` pairs with no `z` field, so an unservable vertical coordinate is unconstructible rather than constructed and then rejected. `Position` does carry `z: float | None` against this future; widening `MultiPoint` to the CoverageJSON `["x", "y", "z"]` composite axis is part of the work.
## How to use
File a focused end-to-end slice issue for each verb as it is scheduled, linked here. Milestone: **Temporal endpoint surface**.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with ADR-0001 and dependency issue #69, then inspect dependencies.py, wkt.py, and geometry.py to understand the current temporal and vertical-selection boundaries. Use the listed endpoint verbs and linked issues #18, #57, and #15 to split this umbrella into focused end-to-end slices; done means each scheduled slice has a linked issue without dropping a temporal or vertical dependency.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100