Uniform Field Specification¶

Overview¶

A uniform 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
There is a uniform step between intermediate expressable values
All parts of the number range are the same resolution

More formally

A uniform field is a numeric telemetry field whose legal values are defined by one continuous numeric range with one uniform step size across the whole range.

This is useful when one fixed resolution is appropriate across the whole measurement range.

Negative values are supported.

Floating-point values and floating-point step sizes are also supported, provided the step size exactly tiles the field range.

A field may want

0 to 100 in steps of 20
-2.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 uniform field?

A uniform field is the simplest compact numeric field definition.

It works well when:

The Entire range can use one resolution
No part of the range needs special treatment
The Field can be represented as one evenly spaced numeric ladder

Example: Altitude¶

Measuring altitude with one fixed resolution

Let's define measuring altitude to be deciding:

Low Value = 0
High Value = 100
Step Size = 20

The legal values are:

0, 20, 40, 60, 80, 100

This is a good fit for a uniform field because the entire range uses the same resolution.

Compaction example

Instead of transmitting the altitude value directly, we can transmit its index in the legal-value list:

Value	`0`	`20`	`40`	`60`	`80`	`100`
Index	`0`	`1`	`2`	`3`	`4`	`5`

By transmitting the index instead of the raw measurement value, the field can often be represented more compactly.

Canonical JSON Form¶

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

{
  "name": "<FieldName>",
  "unit": "<UnitName>",
  "lowValue": <low>,
  "highValue": <high>,
  "stepSize": <step>
}

Formal Specification¶

Field Definition¶

A uniform field definition contains:

lowValue: Low end of the field range (eg 0, -2.5)
highValue: High end of the field range (eg 100, 2.5)
stepSize: Uniform spacing between legal values (eg 20, 0.5)

The field represents one evenly stepped range:

lowValue, lowValue + stepSize, lowValue + 2 * stepSize, ... , highValue

Field Validity Rules¶

A uniform field must satisfy all of the following:

lowValue is finite
highValue is finite
stepSize is finite
lowValue < highValue
stepSize > 0
(highValue - lowValue) / stepSize is an integer

The final rule means the step size must exactly tile the full field range.

Formal note: negative values and floating-point values are fully supported, provided the field still satisfies the exact tiling rule above.

Representable Value Count¶

For a uniform field:

{ lowValue, highValue, stepSize }

the number of legal values is:

((highValue - lowValue) / stepSize) + 1

This value count is the field radix.

Encoding And Decoding Model¶

The purpose of a uniform 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:

Clamp the input to the field range if needed.
Quantize the input onto the legal step grid.
Convert the quantized value into its zero-based index within the field.

For a legal value x:

encoded = (x - lowValue) / stepSize

Decode¶

Decoding proceeds conceptually as follows:

Clamp the packed integer to the legal packed range if needed.
Reconstruct the numeric value from the field index.

decoded = lowValue + (packedValue * stepSize)

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: Whole-Number Uniform Field¶

{
  "name": "Altitude",
  "unit": "Meters",
  "lowValue": 0,
  "highValue": 100,
  "stepSize": 20
}

Legal values:

0, 20, 40, 60, 80, 100

This is the classic uniform-field case: one range, one step size, one uniform resolution throughout.

Example 2: Threshold Between Adjacent Legal Values¶

Given:

{
  "name": "Altitude",
  "unit": "Meters",
  "lowValue": 0,
  "highValue": 100,
  "stepSize": 20
}

Adjacent legal values include:

40
60

The midpoint threshold between them is:

(40 + 60) / 2 = 50

If nearest-value quantization is used:

Values below 50 quantize to 40
Values at or above 50 quantize to 60

Example 3: Negative Floating-Point Uniform Field¶

{
  "name": "ClockDrift",
  "unit": "Milliseconds",
  "lowValue": -2.5,
  "highValue": 2.5,
  "stepSize": 0.5
}

Legal values:

-2.5, -2.0, -1.5, -1.0, -0.5, 0.0, 0.5, 1.0, 1.5, 2.0, 2.5

This demonstrates that uniform fields support both negative values and floating-point step sizes.

Practical Notes¶

A uniform field is one uniform range

Every part of the field uses the same step size.

Negative and floating-point values are allowed

Uniform fields may use negative values and floating-point step sizes, as long as the full range is tiled exactly by the chosen step size.

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.

Uniform fields are the simple case

If one resolution works across the whole range, a uniform field is usually the most straightforward choice.

Summary¶

A uniform field is:

One Numeric field
Defined by one continuous range
Allowed to use one uniform step size across the entire range

Its canonical form is:

{
  lowValue,
  highValue,
  stepSize
}

with:

Exact step tiling across the full field range
One combined ordered set of legal values
One packed integer index per legal value

This makes uniform fields the simplest compact numeric field definition for telemetry.