Segmented Field Specification¶

Overview¶

A segmented field saves space in a range of values

This is done by defining a numeric range of values where:

There is a low value
There is a high value
Some parts of the number range are higher resolution
Some parts of the number range are lower resolution

More formally

A segmented field is a numeric telemetry field whose legal values are defined by multiple contiguous numeric ranges, where each range may use a different step size.

This is useful when one part of a measurement range needs finer resolution than another part, but the result still needs to behave as one encoded field.

A field may want

-25 to -5 in steps of 5
-5 to 5 in steps of 1
5 to 25 in steps of 5
-2.5 to -0.5 in steps of 0.5
-0.5 to 0.5 in steps of 0.1
0.5 to 2.5 in steps of 0.5

This page introduces the idea, gives a formal specification, and shows examples.

Motivation¶

Why use a segmented field instead of one fixed step size?

A single step size is often a poor fit for real telemetry.

If the step is too fine, too many encoded values are spent on regions that do not need that precision.

If the step is too coarse, the part of the range that does matter loses useful detail.

Example: Clock Drift¶

Measuring clock-drift errors near zero than large errors farther away from zero

In that case, a segmented field can use:

Finer steps near zero drift
Coarser steps farther from zero

Example value ranges and resolutions:

-25 to -5 uses 5 ms resolution
-5 to 5 uses 1 ms resolution
5 to 25 uses 5 ms resolution

Legal values are:

-25, -20, -15, -10, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 10, 15, 20, 25

Example tooling

Tooling via Field Calculator.

Chart showing number line and resolution of values:

Automatic C/C++ code generation for use in tracker implementations or review:

Canonical JSON Form¶

This specification uses Traquito-format field definition for illustration purposes.

{
  "name": "<FieldName>",
  "unit": "<UnitName>",
  "valueSegmentList": [
    [low_1, step_1, high_1],
    [low_2, step_2, high_2]
  ]
}

Formal Specification¶

Field Definition¶

A segmented field definition contains:

valueSegmentList: Ordered list of value segments

Each segment is a 3-element list in canonical order:

[low, step, high]

where:

low is the segment minimum (eg 0, -2.5)
step is the representable spacing within the segment (eg 20, 0.5)
high is the segment maximum (eg 100, 2.5)

Segment Validity Rules¶

Each segment must satisfy all of the following:

low is finite
step is finite
high is finite
low < high
step > 0
(high - low) / step is an integer

The final rule means that the step must exactly tile the segment range.

This applies equally to integer and floating-point segments.

Segment Ordering Rules¶

The segments in valueSegmentList are ordered from low numeric range to high numeric range.

Adjacent segments must satisfy:

segment[i].high == segment[i + 1].low

This means:

No gaps between segments
No overlaps between segments
One continuous field across the full range

Boundary Ownership¶

Shared segment boundaries are represented only once.

For every segment except the final segment, the legal values are:

low, low + step, low + 2 * step, ... , high - step

For the final segment, the legal values are:

low, low + step, low + 2 * step, ... , high

This avoids double-counting a shared boundary such as:

[0, 10, 100]
[100, 50, 300]

In that field, 100 belongs only once, as the first value of the second segment.

Representable Value Count¶

For a segment:

[low, step, high]

the number of legal values is:

(high - low) / step for a non-final segment
(high - low) / step + 1 for the final segment

The full field radix is the sum of those counts across all segments.

Encoding And Decoding Model¶

The purpose of a segmented field is to map between:

A physical numeric value
A packed integer value in the range 0 to radix - 1

Encode¶

Encoding proceeds conceptually as follows:

Determine which segment contains the input value.
Quantize the input onto that segment's legal step grid.
Convert the segment-local step index into a field-global packed value by adding the counts of all earlier segments.

Decode¶

Decoding proceeds conceptually as follows:

Determine which segment contains the packed integer.
Convert the packed integer into a segment-local index.
Reconstruct the field value:

decoded = low + (local_index * step)

The encode and decode procedures are therefore simple inverses of one another, provided the same field definition is used on both sides.

Quantization Behavior¶

Inputs are interpreted according to the field definition.

Typical behavior

In practice, implementations commonly:

Clamp values below the field minimum to the field minimum
Clamp values above the field maximum to the field maximum
Quantize values within range to the nearest legal representable value

When nearest-value quantization is used, the threshold between two adjacent representable values is the midpoint between them.

For adjacent legal values a and b, the threshold is:

(a + b) / 2

Examples¶

Example 1: Single-Segment Field¶

[0, 20, 100]

Legal values:

0, 20, 40, 60, 80, 100

This is equivalent to an ordinary uniformly stepped field.

Example 2: Two Segments With Different Resolution¶

[0, 10, 100]
[100, 50, 300]

Legal values become:

First segment: 0, 10, 20, ..., 90
Second segment: 100, 150, 200, 250, 300

This gives:

Fine resolution in the lower range
Coarse resolution in the upper range
One continuous encoded field

Example 3: Negative Floating-Point Segmented Field¶

[-2.5, 0.5, -0.5]
[-0.5, 0.1, 0.5]
[0.5, 0.5, 2.5]

This demonstrates that segmented fields support:

Negative values
Floating-point segment bounds
Floating-point step sizes
Different resolutions in different parts of the range

Example 4: Negative-Only Segmented Field¶

[-120, 20, -40]
[-40, 5, 0]

Legal values become:

First segment: -120, -100, -80, -60
Second segment: -40, -35, -30, -25, -20, -15, -10, -5, 0

This demonstrates that segmented fields do not need to cross zero. They can represent entirely negative ranges while still changing resolution between segments.

Example 5: Floating-Point Segmented Field¶

[0.0, 0.25, 1.0]
[1.0, 0.5, 3.0]

Legal values become:

First segment: 0.0, 0.25, 0.5, 0.75
Second segment: 1.0, 1.5, 2.0, 2.5, 3.0

This demonstrates that segmented fields support floating-point segment bounds and floating-point step sizes even when the full range is non-negative.

Example 6: Mixed Negative, Positive, Integer, And Decimal Field¶

[-12, 2, -4]
[-4, 0.5, 4.5]
[4.5, 1.5, 6]
[6, 2, 14]

Legal values become:

First segment: -12, -10, -8, -6
Second segment: -4.0, -3.5, -3.0, ..., 3.5, 4.0
Third segment: 4.5, 6.0
Fourth segment: 6, 8, 10, 12, 14

This demonstrates that a segmented field can combine:

Negative values
Positive values
Integer step sizes
Decimal step sizes

all within one continuous encoded field.

Practical Notes¶

Segment order matters

Segments are listed in ascending numeric order and are interpreted in that order.

Shared boundaries are structural

If one segment ends at 5, the next must begin at 5.

Negative and floating-point values are allowed

Segmented fields may use negative values and floating-point step sizes, as long as every segment is tiled exactly and adjacent segment boundaries still match exactly.

The field radix is the count of legal values

The total number of representable field values is the number of packed values required to encode the field.

A segmented field is still one field

The segments are an internal definition detail. The encoded result is still one packed field value.

Tools¶

The Field Calculator helps define, inspect, and verify segmented fields

It provides:

Interactive editing of valueSegmentList
Field analysis and radix calculation
Charting of quantization behavior
Encode/decode code generation in C
Export helpers for JSON, URLs, and generated code

The Codec Playground supports this field definition structure