Skip to content

Commit fe61bbe

Browse files
danielkivclaude
danielkiv
and
claude
committed
docs: modernize type syntax and add alias table
- Replace Optional[X] with X | None in get_embedding and get_embeddings_batch signatures (api_embedding.md) and SensorSpec signature (api_specs.md) to match Python 3.12 style - Add complete Legacy Aliases table to models.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 11ccd58 commit fe61bbe

File tree

3 files changed

+128
-112
lines changed

3 files changed

+128
-112
lines changed

‎docs/api_embedding.md‎

Lines changed: 44 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22

33
This page covers single-ROI and batch embedding APIs.
44

5-
65
Related pages: [API: Specs and Data Structures](api_specs.md), [API: Export](api_export.md), and [API: Inspect](api_inspect.md).
76

87
---
@@ -35,10 +34,10 @@ get_embedding(
3534
model: str,
3635
*,
3736
spatial: SpatialSpec,
38-
temporal: Optional[TemporalSpec] = None,
39-
sensor: Optional[SensorSpec] = None,
40-
fetch: Optional[FetchSpec] = None,
41-
modality: Optional[str] = None,
37+
temporal: TemporalSpec | None = None,
38+
sensor: SensorSpec | None = None,
39+
fetch: FetchSpec | None = None,
40+
modality: str | None = None,
4241
output: OutputSpec = OutputSpec.pooled(),
4342
backend: str = "auto",
4443
device: str = "auto",
@@ -53,30 +52,30 @@ Computes the embedding for a single ROI.
5352

5453
Core inputs:
5554

56-
| Parameter | Meaning |
57-
|---|---|
58-
| `model` | Model ID. See [Supported Models](models.md) or call `rs_embed.list_models()`. |
59-
| `spatial` | `BBox` or `PointBuffer`. |
60-
| `temporal` | `TemporalSpec` or `None`. The parameter is optional at the API level, but some models or data sources still require it. |
61-
| `sensor` | Full input descriptor for on-the-fly models. Most precomputed models can leave this as `None`. When provided, it overrides source-level details such as collection, bands, scale, and compositing. |
62-
| `fetch` | Lightweight sampling override for common cases such as `scale_m`, `cloudy_pct`, `composite`, and `fill_value`. It is applied on top of the model's resolved default sensor and cannot be combined with `sensor`. |
63-
| `output` | Usually `OutputSpec.pooled()` or `OutputSpec.grid(...)`. |
55+
| Parameter | Meaning |
56+
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
57+
| `model` | Model ID. See [Supported Models](models.md) or call `rs_embed.list_models()`. |
58+
| `spatial` | `BBox` or `PointBuffer`. |
59+
| `temporal` | `TemporalSpec` or `None`. The parameter is optional at the API level, but some models or data sources still require it. |
60+
| `sensor` | Full input descriptor for on-the-fly models. Most precomputed models can leave this as `None`. When provided, it overrides source-level details such as collection, bands, scale, and compositing. |
61+
| `fetch` | Lightweight sampling override for common cases such as `scale_m`, `cloudy_pct`, `composite`, and `fill_value`. It is applied on top of the model's resolved default sensor and cannot be combined with `sensor`. |
62+
| `output` | Usually `OutputSpec.pooled()` or `OutputSpec.grid(...)`. |
6463

6564
Runtime and branch selection:
6665

67-
| Parameter | Meaning |
68-
|---|---|
69-
| `modality` | Optional model-facing modality selector such as `s1`, `s2`, or `s2_l2a` for models that expose multiple branches. The API normalizes common aliases such as `sentinel-1 -> s1` and `sentinel-2 -> s2`. |
70-
| `backend` | Access backend. `backend="auto"` is the public default and the recommended choice. Precomputed models typically expect `auto`, while provider-backed on-the-fly paths commonly use `gee` through the auto resolver. |
71-
| `device` | `"auto"`, `"cpu"`, or `"cuda"` for torch-backed models. |
72-
| `input_prep` | `"resize"` (default), `"tile"`, `"auto"`, `InputPrepSpec(...)`, or `None`. `None` is treated like the default resize path. |
66+
| Parameter | Meaning |
67+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
68+
| `modality` | Optional model-facing modality selector such as `s1`, `s2`, or `s2_l2a` for models that expose multiple branches. The API normalizes common aliases such as `sentinel-1 -> s1` and `sentinel-2 -> s2`. |
69+
| `backend` | Access backend. `backend="auto"` is the public default and the recommended choice. Precomputed models typically expect `auto`, while provider-backed on-the-fly paths commonly use `gee` through the auto resolver. |
70+
| `device` | `"auto"`, `"cpu"`, or `"cuda"` for torch-backed models. |
71+
| `input_prep` | `"resize"` (default), `"tile"`, `"auto"`, `InputPrepSpec(...)`, or `None`. `None` is treated like the default resize path. |
7372

7473
Model-specific settings:
7574

76-
| Parameter | Meaning |
77-
|---|---|
78-
| `variant` | Common model-specific selector passed through `**model_kwargs`, for example `variant="large"` or `variant="base"`. Only models that declare variant support accept it. |
79-
| `**model_kwargs` | Model-specific settings passed directly as keyword arguments, such as `variant="large"`. Accepted keys depend on the model. |
75+
| Parameter | Meaning |
76+
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
77+
| `variant` | Common model-specific selector passed through `**model_kwargs`, for example `variant="large"` or `variant="base"`. Only models that declare variant support accept it. |
78+
| `**model_kwargs` | Model-specific settings passed directly as keyword arguments, such as `variant="large"`. Accepted keys depend on the model. |
8079

8180
#### Rules And Contracts
8281

@@ -133,10 +132,10 @@ get_embeddings_batch(
133132
model: str,
134133
*,
135134
spatials: List[SpatialSpec],
136-
temporal: Optional[TemporalSpec] = None,
137-
sensor: Optional[SensorSpec] = None,
138-
fetch: Optional[FetchSpec] = None,
139-
modality: Optional[str] = None,
135+
temporal: TemporalSpec | None = None,
136+
sensor: SensorSpec | None = None,
137+
fetch: FetchSpec | None = None,
138+
modality: str | None = None,
140139
output: OutputSpec = OutputSpec.pooled(),
141140
backend: str = "auto",
142141
device: str = "auto",
@@ -151,30 +150,30 @@ Batch-computes embeddings for multiple ROIs using the same embedder instance (of
151150

152151
Core inputs:
153152

154-
| Parameter | Meaning |
155-
|---|---|
156-
| `model` | Model ID. See [Supported Models](models.md) or call `rs_embed.list_models()`. |
157-
| `spatials` | Non-empty `List[SpatialSpec]`. Each item is a `BBox` or `PointBuffer`. Output order matches input order. |
158-
| `temporal` | `TemporalSpec` or `None`. The parameter is optional at the API level, but some models or data sources still require it. |
159-
| `sensor` | Full input descriptor for on-the-fly models. Most precomputed models can leave this as `None`. When provided, it overrides source-level details such as collection, bands, scale, and compositing. |
160-
| `fetch` | Lightweight sampling override for common cases such as `scale_m`, `cloudy_pct`, `composite`, and `fill_value`. It is applied on top of the model's resolved default sensor and cannot be combined with `sensor`. |
161-
| `output` | Usually `OutputSpec.pooled()` or `OutputSpec.grid(...)`. |
153+
| Parameter | Meaning |
154+
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
155+
| `model` | Model ID. See [Supported Models](models.md) or call `rs_embed.list_models()`. |
156+
| `spatials` | Non-empty `List[SpatialSpec]`. Each item is a `BBox` or `PointBuffer`. Output order matches input order. |
157+
| `temporal` | `TemporalSpec` or `None`. The parameter is optional at the API level, but some models or data sources still require it. |
158+
| `sensor` | Full input descriptor for on-the-fly models. Most precomputed models can leave this as `None`. When provided, it overrides source-level details such as collection, bands, scale, and compositing. |
159+
| `fetch` | Lightweight sampling override for common cases such as `scale_m`, `cloudy_pct`, `composite`, and `fill_value`. It is applied on top of the model's resolved default sensor and cannot be combined with `sensor`. |
160+
| `output` | Usually `OutputSpec.pooled()` or `OutputSpec.grid(...)`. |
162161

163162
Runtime and branch selection:
164163

165-
| Parameter | Meaning |
166-
|---|---|
167-
| `modality` | Optional model-facing modality selector such as `s1`, `s2`, or `s2_l2a` for models that expose multiple branches. The API normalizes common aliases such as `sentinel-1 -> s1` and `sentinel-2 -> s2`. |
168-
| `backend` | Access backend. `backend="auto"` is the public default and the recommended choice. Precomputed models typically expect `auto`, while provider-backed on-the-fly paths commonly use `gee` through the auto resolver. |
169-
| `device` | `"auto"`, `"cpu"`, or `"cuda"` for torch-backed models. |
170-
| `input_prep` | `"resize"` (default), `"tile"`, `"auto"`, `InputPrepSpec(...)`, or `None`. `None` is treated like the default resize path. |
164+
| Parameter | Meaning |
165+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
166+
| `modality` | Optional model-facing modality selector such as `s1`, `s2`, or `s2_l2a` for models that expose multiple branches. The API normalizes common aliases such as `sentinel-1 -> s1` and `sentinel-2 -> s2`. |
167+
| `backend` | Access backend. `backend="auto"` is the public default and the recommended choice. Precomputed models typically expect `auto`, while provider-backed on-the-fly paths commonly use `gee` through the auto resolver. |
168+
| `device` | `"auto"`, `"cpu"`, or `"cuda"` for torch-backed models. |
169+
| `input_prep` | `"resize"` (default), `"tile"`, `"auto"`, `InputPrepSpec(...)`, or `None`. `None` is treated like the default resize path. |
171170

172171
Model-specific settings:
173172

174-
| Parameter | Meaning |
175-
|---|---|
176-
| `variant` | Common model-specific selector passed through `**model_kwargs`, for example `variant="large"` or `variant="base"`. Only models that declare variant support accept it. |
177-
| `**model_kwargs` | Model-specific settings passed directly as keyword arguments, such as `variant="large"`. Accepted keys depend on the model. |
173+
| Parameter | Meaning |
174+
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
175+
| `variant` | Common model-specific selector passed through `**model_kwargs`, for example `variant="large"` or `variant="base"`. Only models that declare variant support accept it. |
176+
| `**model_kwargs` | Model-specific settings passed directly as keyword arguments, such as `variant="large"`. Accepted keys depend on the model. |
178177

179178
#### Rules And Contracts
180179

0 commit comments

Comments
 (0)