From c1035e66e1f4fab9dfea6eb4d05cc78c6e5fc926 Mon Sep 17 00:00:00 2001 From: John Bogovic Date: Mon, 20 Jul 2026 19:57:31 -0400 Subject: [PATCH 1/3] add valid fill_value to Uint16 range reduction example * also add brief explanatory sentence --- codecs/scale_offset/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/codecs/scale_offset/README.md b/codecs/scale_offset/README.md index 56e30f8..699b5ab 100644 --- a/codecs/scale_offset/README.md +++ b/codecs/scale_offset/README.md @@ -90,11 +90,12 @@ The following snippet of array metadata demonstrates the metadata for the `scale ### Uint16 range reduction -In this example, a `uint16` array with values in the range `[1000, 1255]` is shifted down by `1000` so that values fall in the range `[0, 255]`, then cast to `uint8` via the `cast_value` codec. +In this example, a `uint16` array with values in the range `[1000, 1255]` is shifted down by `1000` so that values fall in the range `[0, 255]`, then cast to `uint8` via the `cast_value` codec. Note that with these codecs,`fill_value` is constrained to the range `[1000, 1255]`. ```json { "data_type": "uint16", + "fill_value": 1000, "codecs": [ { "name": "scale_offset", @@ -113,6 +114,7 @@ In this example, a `uint16` array with values in the range `[1000, 1255]` is shi } ``` + ### Float64 to uint8 with NaN preservation In this example, a `float64` array with values in the range `[0.0, 2540.0]` and a fill value of `NaN` is stored as `uint8`. The `scale_offset` codec maps values from `[0.0, 2540.0]` to `[1.0, 255.0]` by applying `(x - offset) * scale` with `offset = -10` and `scale = 0.1`, reserving `0` for `NaN`. The `cast_value` codec then casts to `uint8`, using `scalar_map` to explicitly map `NaN` to `0` on encode and `0` to `NaN` on decode. This ensures a lossless round-trip for the fill value. There is no such assurance for From 5ec3afd9a2a2228b4fb08ebd10c04ee57ad6a3bf Mon Sep 17 00:00:00 2001 From: John Bogovic Date: Wed, 22 Jul 2026 10:40:13 -0400 Subject: [PATCH 2/3] add second uint16 range reduction example * prepend with cast_value with scalar_map enables use of any fill_value --- codecs/scale_offset/README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/codecs/scale_offset/README.md b/codecs/scale_offset/README.md index 699b5ab..9d88cf1 100644 --- a/codecs/scale_offset/README.md +++ b/codecs/scale_offset/README.md @@ -114,6 +114,40 @@ In this example, a `uint16` array with values in the range `[1000, 1255]` is shi } ``` +Using a adding a `cast_value` codec with a `scalar_map` makes it possible for any `fill_value` to be used by mapping it into the valid range without changing the data type. Here, first mapping the `fill_value` `0 → 1000` has equivalent behavior to the example above. + +```json +{ + "data_type": "uint16", + "fill_value": 0, + "codecs": [ + { + "name": "cast_value", + "configuration": { + "data_type": "uint16" + "scalar_map": { + "encode": [[0, 1000]], + "decode": [[1000, 0]] + } + } + }, + { + "name": "scale_offset", + "configuration": { + "offset": 1000 + } + }, + { + "name": "cast_value", + "configuration": { + "data_type": "uint8" + } + }, + "bytes" + ] +} +``` + ### Float64 to uint8 with NaN preservation From 73c3608e1832ecaa028cc79d836ab19f126f5d58 Mon Sep 17 00:00:00 2001 From: John Bogovic Date: Wed, 22 Jul 2026 16:32:24 -0400 Subject: [PATCH 3/3] Update codecs/scale_offset/README.md Co-authored-by: Davis Bennett --- codecs/scale_offset/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/codecs/scale_offset/README.md b/codecs/scale_offset/README.md index 9d88cf1..92415e1 100644 --- a/codecs/scale_offset/README.md +++ b/codecs/scale_offset/README.md @@ -114,7 +114,7 @@ In this example, a `uint16` array with values in the range `[1000, 1255]` is shi } ``` -Using a adding a `cast_value` codec with a `scalar_map` makes it possible for any `fill_value` to be used by mapping it into the valid range without changing the data type. Here, first mapping the `fill_value` `0 → 1000` has equivalent behavior to the example above. +Using a `cast_value` codec with a `scalar_map` makes it possible for any `fill_value` to be used by mapping it into the valid range without changing the data type. Here, first mapping the `fill_value` `0 → 1000` has equivalent behavior to the example above. ```json {