robot-models-lib 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. robot_models/__init__.py +18 -0
  2. robot_models/actuators/__init__.py +1 -0
  3. robot_models/actuators/rungs/README.md +24 -0
  4. robot_models/actuators/rungs/coulomb_viscous/README.md +61 -0
  5. robot_models/actuators/rungs/coulomb_viscous/model.js +14 -0
  6. robot_models/actuators/rungs/coulomb_viscous/model.json +102 -0
  7. robot_models/actuators/rungs/coulomb_viscous/model.py +24 -0
  8. robot_models/actuators/rungs/datasheet/README.md +65 -0
  9. robot_models/actuators/rungs/datasheet/model.js +14 -0
  10. robot_models/actuators/rungs/datasheet/model.json +138 -0
  11. robot_models/actuators/rungs/datasheet/model.py +24 -0
  12. robot_models/actuators/rungs/dcmotor/README.md +63 -0
  13. robot_models/actuators/rungs/dcmotor/model.json +163 -0
  14. robot_models/actuators/rungs/ideal/README.md +60 -0
  15. robot_models/actuators/rungs/ideal/model.js +6 -0
  16. robot_models/actuators/rungs/ideal/model.json +90 -0
  17. robot_models/actuators/rungs/ideal/model.py +13 -0
  18. robot_models/actuators/rungs/load/README.md +65 -0
  19. robot_models/actuators/rungs/load/model.js +15 -0
  20. robot_models/actuators/rungs/load/model.json +117 -0
  21. robot_models/actuators/rungs/load/model.py +25 -0
  22. robot_models/actuators/rungs/lugre/README.md +72 -0
  23. robot_models/actuators/rungs/lugre/model.js +24 -0
  24. robot_models/actuators/rungs/lugre/model.json +164 -0
  25. robot_models/actuators/rungs/lugre/model.py +30 -0
  26. robot_models/actuators/rungs/ripple/README.md +64 -0
  27. robot_models/actuators/rungs/ripple/model.js +17 -0
  28. robot_models/actuators/rungs/ripple/model.json +119 -0
  29. robot_models/actuators/rungs/ripple/model.py +27 -0
  30. robot_models/actuators/rungs/stribeck/README.md +65 -0
  31. robot_models/actuators/rungs/stribeck/model.js +17 -0
  32. robot_models/actuators/rungs/stribeck/model.json +126 -0
  33. robot_models/actuators/rungs/stribeck/model.py +28 -0
  34. robot_models/actuators/servo/README.md +278 -0
  35. robot_models/actuators/servo/__init__.py +7 -0
  36. robot_models/actuators/servo/bldc/README.md +186 -0
  37. robot_models/actuators/servo/bldc/__init__.py +5 -0
  38. robot_models/actuators/servo/bldc/bldc_motor.py +93 -0
  39. robot_models/actuators/servo/bldc/ladder.py +268 -0
  40. robot_models/actuators/servo/foc_controller/README.md +127 -0
  41. robot_models/actuators/servo/foc_controller/__init__.py +3 -0
  42. robot_models/actuators/servo/foc_controller/ladder.py +207 -0
  43. robot_models/actuators/servo/gearbox/README.md +148 -0
  44. robot_models/actuators/servo/gearbox/__init__.py +5 -0
  45. robot_models/actuators/servo/gearbox/gearbox.py +36 -0
  46. robot_models/actuators/servo/gearbox/ladder.py +214 -0
  47. robot_models/actuators/servo/integrated_servo.py +33 -0
  48. robot_models/actuators/servo/ladder.py +593 -0
  49. robot_models/arms/__init__.py +1 -0
  50. robot_models/arms/rigid_body_chain/README.md +151 -0
  51. robot_models/arms/rigid_body_chain/__init__.py +3 -0
  52. robot_models/arms/rigid_body_chain/ladder.py +228 -0
  53. robot_models/conveyors/__init__.py +1 -0
  54. robot_models/conveyors/conveyor/README.md +140 -0
  55. robot_models/conveyors/conveyor/__init__.py +1 -0
  56. robot_models/conveyors/conveyor/ladder.py +203 -0
  57. robot_models/datasheet/__init__.py +56 -0
  58. robot_models/datasheet/datasheet.py +355 -0
  59. robot_models/datasheet/literal.py +144 -0
  60. robot_models/datasheet/source.py +328 -0
  61. robot_models/datasheet/stated.py +135 -0
  62. robot_models/datasheet/units.py +57 -0
  63. robot_models/end_effectors/__init__.py +1 -0
  64. robot_models/end_effectors/gripper/README.md +112 -0
  65. robot_models/end_effectors/gripper/__init__.py +3 -0
  66. robot_models/end_effectors/gripper/ladder.py +150 -0
  67. robot_models/homing/__init__.py +38 -0
  68. robot_models/homing/cad_bundle.py +206 -0
  69. robot_models/homing/contact.py +201 -0
  70. robot_models/homing/fit.py +126 -0
  71. robot_models/homing/metrics.py +237 -0
  72. robot_models/homing/protocols.py +72 -0
  73. robot_models/homing/types.py +256 -0
  74. robot_models/ladder.py +645 -0
  75. robot_models/markers/__init__.py +1 -0
  76. robot_models/markers/aruco_marker/README.md +92 -0
  77. robot_models/markers/aruco_marker/__init__.py +2 -0
  78. robot_models/markers/aruco_marker/ladder.py +142 -0
  79. robot_models/references.py +429 -0
  80. robot_models/sensors/__init__.py +1 -0
  81. robot_models/sensors/camera/README.md +118 -0
  82. robot_models/sensors/camera/__init__.py +3 -0
  83. robot_models/sensors/camera/ladder.py +108 -0
  84. robot_models/sensors/encoder/README.md +103 -0
  85. robot_models/sensors/encoder/__init__.py +5 -0
  86. robot_models/sensors/encoder/ladder.py +133 -0
  87. robot_models/sensors/hyperspectral_camera/README.md +107 -0
  88. robot_models/sensors/hyperspectral_camera/__init__.py +1 -0
  89. robot_models/sensors/hyperspectral_camera/ladder.py +151 -0
  90. robot_models/sensors/rgbd/README.md +113 -0
  91. robot_models/sensors/rgbd/__init__.py +5 -0
  92. robot_models/sensors/rgbd/ladder.py +113 -0
  93. robot_models_lib-0.2.0.dist-info/METADATA +143 -0
  94. robot_models_lib-0.2.0.dist-info/RECORD +96 -0
  95. robot_models_lib-0.2.0.dist-info/WHEEL +4 -0
  96. robot_models_lib-0.2.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,118 @@
1
+ > **Generated file.** Written by [`tools/make_type_docs.py`](../../../../tools/make_type_docs.py) from this folder's [`ladder.py`](ladder.py): edit the ladder, not this file, then run `python tools/make_type_docs.py` from the repository root.
2
+
3
+ # camera
4
+
5
+ A frame camera's colour image: projection, distortion, exposure.
6
+
7
+ **6 rungs** · 8 parameters · 5 aliases · 0 packed names · 0 deployment-only names · folder `sensors/camera/`.
8
+
9
+ In code: `ladders()["camera"]` from [`robot_models.ladder`](../../ladder.py). Every type: [docs/TYPES.md](../../../../docs/TYPES.md). Spec: [PEP 0004](../../../../docs/peps/0004-model-ladders-by-type.md).
10
+
11
+ ## About
12
+
13
+ From the docstring of [`ladder.py`](ladder.py), less a paragraph on the order that file reads in (this page shows the ladder, then the rungs, then the names):
14
+
15
+ Spec: PEP 0004 §5.7 and §6.6.
16
+
17
+ The ladder climbs from the ideal pinhole (M0) through the lens (M1), the sensor's light response and the frame's delay
18
+ (M2), a rolling shutter (M3) and a mount that loosens with vibration (M3.wear), to a grey-box correction of every
19
+ pixel's ray (M6). There is no black-box rung: every rung stays a geometric pixel-to-ray model that a calibration target
20
+ can measure, and a learned image-to-image black box gives no rays to check.
21
+
22
+ ## The ladder
23
+
24
+ ```mermaid
25
+ flowchart BT
26
+ M0_pinhole["M0.pinhole<br/>Pinhole projection"]
27
+ M1_distortion["M1.distortion<br/>Brown-Conrady distortion"]
28
+ M2_exposure_latency["M2.exposure_latency<br/>Exposure response and<br/>latency"]
29
+ M3_rolling_shutter["M3.rolling_shutter<br/>Rolling shutter: a line<br/>delay"]
30
+ M3_wear["M3.wear<br/>A mount that loosens<br/>over vibration hours"]
31
+ M6_residual{{"M6.residual<br/>Grey-box residual on<br/>M3.wear"}}
32
+ M0_pinhole --> M1_distortion
33
+ M1_distortion --> M2_exposure_latency
34
+ M2_exposure_latency --> M3_rolling_shutter
35
+ M3_rolling_shutter --> M3_wear
36
+ M3_wear --> M6_residual
37
+ classDef physics fill:#e8f1fb,stroke:#2f6aa3,color:#10243a
38
+ classDef wear fill:#e8f1fb,stroke:#2f6aa3,color:#10243a,stroke-dasharray:6 3
39
+ classDef residual fill:#fdf0dc,stroke:#b06a00,color:#3a2400
40
+ class M0_pinhole,M1_distortion,M2_exposure_latency,M3_rolling_shutter physics
41
+ class M3_wear wear
42
+ class M6_residual residual
43
+ ```
44
+
45
+ Read it bottom up: each solid arrow runs from a rung's base to the rung that extends it, and a rung needs everything below it on its own chain (its fallback). Blue box: a physics rung; dashed blue box: a wear rung (a parameter that grows with use); amber hexagon: the grey-box residual (M6) on a physics rung.
46
+
47
+ ## Rungs
48
+
49
+ Bottom up. *Needs* is what the rung's model cannot run without, new over its base; *reads when stated* is what it uses when a source states it. A rung needs everything its base needs.
50
+
51
+ | rung | title | base | needs (adds) | reads when stated (optional) | code | equation | references |
52
+ | --- | --- | --- | --- | --- | --- | --- | --- |
53
+ | <a id="rung-m0-pinhole"></a>`M0.pinhole` | Pinhole projection | — | `fx_fy`, `cx_cy`, `extrinsics` | — | — | `p = K [R \| t] X, K from fx_fy and cx_cy, [R \| t] the extrinsics` | [ZHANG_2000](#ref-zhang_2000) |
54
+ | <a id="rung-m1-distortion"></a>`M1.distortion` | Brown-Conrady distortion | [`M0.pinhole`](#rung-m0-pinhole) | `distortion` | — | — | `radial (k1, k2, k3) and tangential (p1, p2) distortion of the projected point` | [ZHANG_2000](#ref-zhang_2000), [BROWN_1966](#ref-brown_1966), [HEIKKILA_1997](#ref-heikkila_1997) |
55
+ | <a id="rung-m2-exposure_latency"></a>`M2.exposure_latency` | Exposure response and latency | [`M1.distortion`](#rung-m1-distortion) | `exposure_response`, `latency` | — | — | `DN = exposure_response·illuminance·exposure time; the frame arrives latency after exposure` | [ZHANG_2000](#ref-zhang_2000) |
56
+ | <a id="rung-m3-rolling_shutter"></a>`M3.rolling_shutter` | Rolling shutter: a line delay | [`M2.exposure_latency`](#rung-m2-exposure_latency) | `line_delay` | — | — | `row v exposed at t0 + v·line_delay` | [OTH_2013](#ref-oth_2013), [MEINGAST_2005](#ref-meingast_2005) |
57
+ | <a id="rung-m3-wear"></a>`M3.wear` | A mount that loosens over vibration hours<br>wears `extrinsics`: see [Wear](#wear) | [`M3.rolling_shutter`](#rung-m3-rolling_shutter) | `extrinsic_drift` | — | — | `translation offset(h) = e + extrinsic_drift·√h` | [JUNKER_1969](#ref-junker_1969), [WHITMORE_1995](#ref-whitmore_1995) |
58
+ | <a id="rung-m6-residual"></a>`M6.residual` | Grey-box residual on M3.wear | [`M3.wear`](#rung-m3-wear) | — | — | — | `M3.wear + a B-spline grid of ray offsets over the pixel (u, v)` | [SCHOPS_2020](#ref-schops_2020) |
59
+
60
+ ## Wear
61
+
62
+ Which parameter grows with use, with what, by which law, at which rate.
63
+
64
+ | rung | parameter that wears | grows with | law | rate |
65
+ | --- | --- | --- | --- | --- |
66
+ | [`M3.wear`](#rung-m3-wear) | [`extrinsics`](#param-extrinsics) | vibration hours (h) | sqrt: `p(u) = p0 + k·√u` | [`extrinsic_drift`](#param-extrinsic_drift) |
67
+
68
+ ## Vocabulary
69
+
70
+ Every parameter the ladder holds, by the rung that first reads it. — as a unit: dimensionless (a ratio or a count).
71
+
72
+ | parameter | SI unit | shape | definition | first read on |
73
+ | --- | --- | --- | --- | --- |
74
+ | <a id="param-fx_fy"></a>`fx_fy` | px | pair | Focal lengths in pixels, (fx, fy). | [`M0.pinhole`](#rung-m0-pinhole) |
75
+ | <a id="param-cx_cy"></a>`cx_cy` | px | pair | Principal point in pixels, (cx, cy). | [`M0.pinhole`](#rung-m0-pinhole) |
76
+ | <a id="param-extrinsics"></a>`extrinsics` | m, rad | pose | The camera's pose in the frame it is calibrated against. | [`M0.pinhole`](#rung-m0-pinhole) |
77
+ | <a id="param-distortion"></a>`distortion` | — | list | Brown-Conrady lens distortion coefficients, radial and tangential. | [`M1.distortion`](#rung-m1-distortion) |
78
+ | <a id="param-exposure_response"></a>`exposure_response` | DN/(lx·s) | scalar | Pixel value per unit of light exposure: the sensor's response. | [`M2.exposure_latency`](#rung-m2-exposure_latency) |
79
+ | <a id="param-latency"></a>`latency` | s | scalar | Delay from exposure to the frame's arrival. | [`M2.exposure_latency`](#rung-m2-exposure_latency) |
80
+ | <a id="param-line_delay"></a>`line_delay` | s | scalar | Rolling shutter: the time between the exposures of successive rows. | [`M3.rolling_shutter`](#rung-m3-rolling_shutter) |
81
+ | <a id="param-extrinsic_drift"></a>`extrinsic_drift` | m/√h | scalar | How fast the extrinsics' translation drifts with the square root of vibration hours (a loosening mount); no source states a rotation rate. | [`M3.wear`](#rung-m3-wear) |
82
+
83
+ ## Aliases
84
+
85
+ Other names a source uses for one of these parameters. A note says how it differs when it is not the same quantity one for one. The unit is the one the source writes its values in; *(canonical)* after it marks an alias stored with no unit of its own, which robot_models reads as the canonical parameter's SI unit, shown here spelled out. A note can still qualify that unit.
86
+
87
+ | alias | canonical | unit | note |
88
+ | --- | --- | --- | --- |
89
+ | `camera_latency_ms` | [`latency`](#param-latency) | ms | |
90
+ | `camera_latency_s` | [`latency`](#param-latency) | s *(canonical)* | |
91
+ | `extrinsic_drift_mm_per_sqrt_h` | [`extrinsic_drift`](#param-extrinsic_drift) | mm/√h | |
92
+ | `latency_s` | [`latency`](#param-latency) | s *(canonical)* | |
93
+ | `line_delay_s` | [`line_delay`](#param-line_delay) | s *(canonical)* | |
94
+
95
+ ## Packed names
96
+
97
+ Names for one array that carries several of these parameters; never read as one parameter.
98
+
99
+ None.
100
+
101
+ ## Deployment-only names
102
+
103
+ Names some model reads that are not the type's own: a deployment sets them, or the mount gives them.
104
+
105
+ None.
106
+
107
+ ## References
108
+
109
+ The works the rungs cite, by their names in [`robot_models.references`](../../references.py).
110
+
111
+ - <a id="ref-brown_1966"></a>**BROWN_1966**: Brown (1966). Decentering distortion of lenses. Photogrammetric Engineering. no stable URL or DOI. What the rung uses: the radial and tangential (Brown-Conrady) distortion model; no stable URL. Cited by [`M1.distortion`](#rung-m1-distortion).
112
+ - <a id="ref-heikkila_1997"></a>**HEIKKILA_1997**: Heikkilä, Silvén (1997). A four-step camera calibration procedure with implicit image correction. IEEE Conference on Computer Vision and Pattern Recognition. [doi:10.1109/CVPR.1997.609468](https://doi.org/10.1109/CVPR.1997.609468). What the rung uses: pinhole + radial and tangential distortion fitted together. Cited by [`M1.distortion`](#rung-m1-distortion).
113
+ - <a id="ref-junker_1969"></a>**JUNKER_1969**: Junker (1969). New criteria for self-loosening of fasteners under vibration. SAE Technical Paper. [doi:10.4271/690055](https://doi.org/10.4271/690055). What the rung uses: a mount loosening under transverse vibration. Cited by [`M3.wear`](#rung-m3-wear).
114
+ - <a id="ref-meingast_2005"></a>**MEINGAST_2005**: Meingast, Geyer, Sastry (2005). Geometric models of rolling-shutter cameras. arXiv:cs/0503076. [https://arxiv.org/abs/cs/0503076](https://arxiv.org/abs/cs/0503076) (preprint). What the rung uses: each row exposed at its own time. Cited by [`M3.rolling_shutter`](#rung-m3-rolling_shutter).
115
+ - <a id="ref-oth_2013"></a>**OTH_2013**: Oth, Furgale, Kneip, Siegwart (2013). Rolling shutter camera calibration. IEEE Conference on Computer Vision and Pattern Recognition. [doi:10.1109/CVPR.2013.179](https://doi.org/10.1109/CVPR.2013.179). What the rung uses: the line delay of a rolling shutter, calibrated. Cited by [`M3.rolling_shutter`](#rung-m3-rolling_shutter).
116
+ - <a id="ref-schops_2020"></a>**SCHOPS_2020**: Schöps, Larsson, Pollefeys, Sattler (2020). Why having 10,000 parameters in your camera model is better than twelve. IEEE/CVF Conference on Computer Vision and Pattern Recognition. [doi:10.1109/CVPR42600.2020.00261](https://doi.org/10.1109/CVPR42600.2020.00261). What the rung uses: a dense B-spline generic camera model above the parametric one. Cited by [`M6.residual`](#rung-m6-residual).
117
+ - <a id="ref-whitmore_1995"></a>**WHITMORE_1995**: Whitmore (1995). Estimating degradation by a Wiener diffusion process subject to measurement error. Lifetime Data Analysis. [doi:10.1007/BF00985762](https://doi.org/10.1007/BF00985762). What the rung uses: diffusive drift: its expected size grows as the square root of time. Cited by [`M3.wear`](#rung-m3-wear).
118
+ - <a id="ref-zhang_2000"></a>**ZHANG_2000**: Zhang (2000). A flexible new technique for camera calibration. IEEE Transactions on Pattern Analysis and Machine Intelligence. [doi:10.1109/34.888718](https://doi.org/10.1109/34.888718). What the rung uses: pinhole intrinsics from a planar target in several poses. Cited by [`M0.pinhole`](#rung-m0-pinhole), [`M1.distortion`](#rung-m1-distortion), [`M2.exposure_latency`](#rung-m2-exposure_latency).
@@ -0,0 +1,3 @@
1
+ """The `camera` type: a frame camera's colour image, from the ideal pinhole through lens distortion, exposure response
2
+ and latency, a rolling shutter and a loosening mount, to a grey-box ray-offset residual. The model ladder lives in
3
+ `ladder.py`; the colour stream of a depth camera is this type too."""
@@ -0,0 +1,108 @@
1
+ """A frame camera's colour image: projection, distortion, exposure (PEP 0004).
2
+
3
+ Spec: PEP 0004 §5.7 and §6.6.
4
+
5
+ The ladder climbs from the ideal pinhole (M0) through the lens (M1), the sensor's light response and the frame's delay
6
+ (M2), a rolling shutter (M3) and a mount that loosens with vibration (M3.wear), to a grey-box correction of every
7
+ pixel's ray (M6). There is no black-box rung: every rung stays a geometric pixel-to-ray model that a calibration target
8
+ can measure, and a learned image-to-image black box gives no rays to check.
9
+
10
+ Read it top down: the vocabulary, grouped by the rung that first reads each name; then the rungs, M0 upward; then the
11
+ aliases. This type has no packed names and nothing deployment-only.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from robot_models import references as refs
17
+ from robot_models.ladder import Alias, Ladder, Parameter, Rung, Wear
18
+
19
+ # --- the vocabulary, by the rung that first reads each name -----------------------------------------------------------
20
+
21
+ M0_PINHOLE = (
22
+ Parameter(name="fx_fy", unit="px", shape="pair", definition="Focal lengths in pixels, (fx, fy)."),
23
+ Parameter(name="cx_cy", unit="px", shape="pair", definition="Principal point in pixels, (cx, cy)."),
24
+ Parameter(name="extrinsics", unit="m, rad", shape="pose",
25
+ definition="The camera's pose in the frame it is calibrated against."),
26
+ )
27
+ M1_DISTORTION = (
28
+ Parameter(name="distortion", unit="", shape="list",
29
+ definition="Brown-Conrady lens distortion coefficients, radial and tangential."),
30
+ )
31
+ M2_EXPOSURE_LATENCY = (
32
+ Parameter(name="exposure_response", unit="DN/(lx·s)", shape="scalar",
33
+ definition="Pixel value per unit of light exposure: the sensor's response."),
34
+ Parameter(name="latency", unit="s", shape="scalar", definition="Delay from exposure to the frame's arrival."),
35
+ )
36
+ M3_ROLLING_SHUTTER = (
37
+ Parameter(name="line_delay", unit="s", shape="scalar",
38
+ definition="Rolling shutter: the time between the exposures of successive rows."),
39
+ )
40
+ M3_WEAR = (
41
+ # WHY no rotation rate (PEP 0004 §5.7): no source states one, so only the translation drifts.
42
+ Parameter(name="extrinsic_drift", unit="m/√h", shape="scalar",
43
+ definition=("How fast the extrinsics' translation drifts with the square root of vibration hours (a "
44
+ "loosening mount); no source states a rotation rate.")),
45
+ )
46
+
47
+ # --- the rungs, M0 upward ---------------------------------------------------------------------------------------------
48
+
49
+ RUNGS = (
50
+ Rung(
51
+ level=0, name="pinhole", title="Pinhole projection", base=None,
52
+ adds=("fx_fy", "cx_cy", "extrinsics"),
53
+ equation="p = K [R | t] X, K from fx_fy and cx_cy, [R | t] the extrinsics",
54
+ references=(refs.ZHANG_2000,),
55
+ ),
56
+ Rung(
57
+ level=1, name="distortion", title="Brown-Conrady distortion", base="M0.pinhole",
58
+ adds=("distortion",),
59
+ equation="radial (k1, k2, k3) and tangential (p1, p2) distortion of the projected point",
60
+ references=(refs.ZHANG_2000, refs.BROWN_1966, refs.HEIKKILA_1997),
61
+ ),
62
+ Rung(
63
+ level=2, name="exposure_latency", title="Exposure response and latency", base="M1.distortion",
64
+ adds=("exposure_response", "latency"),
65
+ equation="DN = exposure_response·illuminance·exposure time; the frame arrives latency after exposure",
66
+ references=(refs.ZHANG_2000,),
67
+ ),
68
+ Rung(
69
+ level=3, name="rolling_shutter", title="Rolling shutter: a line delay", base="M2.exposure_latency",
70
+ adds=("line_delay",),
71
+ equation="row v exposed at t0 + v·line_delay",
72
+ references=(refs.OTH_2013, refs.MEINGAST_2005),
73
+ ),
74
+ Rung(
75
+ level=3, name="wear", title="A mount that loosens over vibration hours", base="M3.rolling_shutter",
76
+ adds=("extrinsic_drift",),
77
+ wears=(Wear(parameter="extrinsics", usage="vibration hours", usage_unit="h", law="sqrt",
78
+ rate="extrinsic_drift"),),
79
+ equation="translation offset(h) = e + extrinsic_drift·√h",
80
+ references=(refs.JUNKER_1969, refs.WHITMORE_1995),
81
+ ),
82
+ Rung(
83
+ # WHY residual and no learned rung: the grid corrects each pixel's ray, so the model stays a pixel-to-ray map a
84
+ # calibration target can measure; a black box gives no rays to check. Source: sim2real's camera_rgb card, the
85
+ # note on its M6 rung (PEP 0004 §5.7 lists the rung and its parameters, not the reason).
86
+ level=6, name="residual", title="Grey-box residual on M3.wear", base="M3.wear", kind="residual",
87
+ equation="M3.wear + a B-spline grid of ray offsets over the pixel (u, v)",
88
+ references=(refs.SCHOPS_2020,),
89
+ ),
90
+ )
91
+
92
+ # --- other names for the same quantities (PEP 0004 §6.6) --------------------------------------------------------------
93
+
94
+ ALIASES = (
95
+ Alias(name="latency_s", canonical="latency"),
96
+ Alias(name="camera_latency_s", canonical="latency"),
97
+ Alias(name="camera_latency_ms", canonical="latency", unit="ms"),
98
+ Alias(name="line_delay_s", canonical="line_delay"),
99
+ Alias(name="extrinsic_drift_mm_per_sqrt_h", canonical="extrinsic_drift", unit="mm/√h"),
100
+ )
101
+
102
+ LADDER = Ladder(
103
+ type="camera",
104
+ title="A frame camera's colour image: projection, distortion, exposure.",
105
+ vocabulary=(*M0_PINHOLE, *M1_DISTORTION, *M2_EXPOSURE_LATENCY, *M3_ROLLING_SHUTTER, *M3_WEAR),
106
+ rungs=RUNGS,
107
+ aliases=ALIASES,
108
+ )
@@ -0,0 +1,103 @@
1
+ > **Generated file.** Written by [`tools/make_type_docs.py`](../../../../tools/make_type_docs.py) from this folder's [`ladder.py`](ladder.py): edit the ladder, not this file, then run `python tools/make_type_docs.py` from the repository root.
2
+
3
+ # encoder
4
+
5
+ An angle sensor on a shaft, such as a drive's rotor encoder.
6
+
7
+ **4 rungs** · 5 parameters · 6 aliases · 0 packed names · 0 deployment-only names · folder `sensors/encoder/`.
8
+
9
+ In code: `ladders()["encoder"]` from [`robot_models.ladder`](../../ladder.py). Every type: [docs/TYPES.md](../../../../docs/TYPES.md). Spec: [PEP 0004](../../../../docs/peps/0004-model-ladders-by-type.md).
10
+
11
+ ## About
12
+
13
+ From the docstring of [`ladder.py`](ladder.py):
14
+
15
+ The reading is the shaft's angle, quantised to counts_per_rev (M0), with noise and a delay (M1), plus an angle error
16
+ that repeats with the shaft angle (M2.eccentricity), which grows over vibration hours as the mount loosens (M2.wear).
17
+
18
+ Spec: PEP 0004 §5.6 and §6.5.
19
+
20
+ ## The ladder
21
+
22
+ ```mermaid
23
+ flowchart BT
24
+ M0_quantiser["M0.quantiser<br/>An ideal quantiser"]
25
+ M1_noise_latency["M1.noise_latency<br/>Noise and latency"]
26
+ M2_eccentricity["M2.eccentricity<br/>Eccentricity harmonics"]
27
+ M2_wear["M2.wear<br/>A mount that loosens<br/>over vibration hours"]
28
+ M0_quantiser --> M1_noise_latency
29
+ M1_noise_latency --> M2_eccentricity
30
+ M2_eccentricity --> M2_wear
31
+ classDef physics fill:#e8f1fb,stroke:#2f6aa3,color:#10243a
32
+ classDef wear fill:#e8f1fb,stroke:#2f6aa3,color:#10243a,stroke-dasharray:6 3
33
+ class M0_quantiser,M1_noise_latency,M2_eccentricity physics
34
+ class M2_wear wear
35
+ ```
36
+
37
+ Read it bottom up: each solid arrow runs from a rung's base to the rung that extends it, and a rung needs everything below it on its own chain (its fallback). Blue box: a physics rung; dashed blue box: a wear rung (a parameter that grows with use).
38
+
39
+ ## Rungs
40
+
41
+ Bottom up. *Needs* is what the rung's model cannot run without, new over its base; *reads when stated* is what it uses when a source states it. A rung needs everything its base needs.
42
+
43
+ | rung | title | base | needs (adds) | reads when stated (optional) | code | equation | references |
44
+ | --- | --- | --- | --- | --- | --- | --- | --- |
45
+ | <a id="rung-m0-quantiser"></a>`M0.quantiser` | An ideal quantiser | — | `counts_per_rev` | — | — | `q_reported = round(q/lsb)·lsb, lsb = 2π/counts_per_rev` | [WIDROW_2008](#ref-widrow_2008) |
46
+ | <a id="rung-m1-noise_latency"></a>`M1.noise_latency` | Noise and latency | [`M0.quantiser`](#rung-m0-quantiser) | `noise_sigma`, `latency` | — | — | `q_reported(t) = round((q(t − latency) + n)/lsb)·lsb, n ~ N(0, noise_sigma²)` | [MERRY_2010](#ref-merry_2010) |
47
+ | <a id="rung-m2-eccentricity"></a>`M2.eccentricity` | Eccentricity harmonics | [`M1.noise_latency`](#rung-m1-noise_latency) | `eccentricity_harmonics` | — | — | `q_reported = round((q + e(q) + n)/lsb)·lsb, delayed; e(q) the eccentricity harmonics` | [ZHAO_2024](#ref-zhao_2024) |
48
+ | <a id="rung-m2-wear"></a>`M2.wear` | A mount that loosens over vibration hours<br>wears `eccentricity_harmonics`: see [Wear](#wear) | [`M2.eccentricity`](#rung-m2-eccentricity) | `eccentricity_growth` | — | — | `amplitude_k(h) = amplitude_k + eccentricity_growth·√h for each eccentricity harmonic (its harmonic and phase stay)` | [JUNKER_1969](#ref-junker_1969), [WHITMORE_1995](#ref-whitmore_1995) |
49
+
50
+ ## Wear
51
+
52
+ Which parameter grows with use, with what, by which law, at which rate.
53
+
54
+ | rung | parameter that wears | grows with | law | rate |
55
+ | --- | --- | --- | --- | --- |
56
+ | [`M2.wear`](#rung-m2-wear) | [`eccentricity_harmonics`](#param-eccentricity_harmonics) | vibration hours (h) | sqrt: `p(u) = p0 + k·√u` | [`eccentricity_growth`](#param-eccentricity_growth) |
57
+
58
+ ## Vocabulary
59
+
60
+ Every parameter the ladder holds, by the rung that first reads it. — as a unit: dimensionless (a ratio or a count).
61
+
62
+ | parameter | SI unit | shape | definition | first read on |
63
+ | --- | --- | --- | --- | --- |
64
+ | <a id="param-counts_per_rev"></a>`counts_per_rev` | 1/rev | integer | Distinct readings per revolution of the shaft it reads: its quantisation. | [`M0.quantiser`](#rung-m0-quantiser) |
65
+ | <a id="param-noise_sigma"></a>`noise_sigma` | rad | scalar | Standard deviation of the reading's noise at standstill. | [`M1.noise_latency`](#rung-m1-noise_latency) |
66
+ | <a id="param-latency"></a>`latency` | s | scalar | Delay from the shaft's angle to the reading that reports it. | [`M1.noise_latency`](#rung-m1-noise_latency) |
67
+ | <a id="param-eccentricity_harmonics"></a>`eccentricity_harmonics` | rad | list | Angle error periodic in the shaft angle (an eccentric magnet or disc), a list of (harmonic, amplitude, phase). | [`M2.eccentricity`](#rung-m2-eccentricity) |
68
+ | <a id="param-eccentricity_growth"></a>`eccentricity_growth` | rad/√h | scalar | How fast the eccentricity grows with the square root of vibration hours (a loosening mount). | [`M2.wear`](#rung-m2-wear) |
69
+
70
+ ## Aliases
71
+
72
+ Other names a source uses for one of these parameters. A note says how it differs when it is not the same quantity one for one. The unit is the one the source writes its values in; *(canonical)* after it marks an alias stored with no unit of its own, which robot_models reads as the canonical parameter's SI unit, shown here spelled out. A note can still qualify that unit.
73
+
74
+ | alias | canonical | unit | note |
75
+ | --- | --- | --- | --- |
76
+ | `eccentricity_growth_mrad_per_sqrt_h` | [`eccentricity_growth`](#param-eccentricity_growth) | mrad/√h | |
77
+ | `encoder_bits` | [`counts_per_rev`](#param-counts_per_rev) | 1/rev *(canonical)* | Bits: 2^bits counts per revolution. |
78
+ | `encoder_counts` | [`counts_per_rev`](#param-counts_per_rev) | 1/rev *(canonical)* | |
79
+ | `encoder_counts_per_rev` | [`counts_per_rev`](#param-counts_per_rev) | 1/rev *(canonical)* | |
80
+ | `encoder_lines` | [`counts_per_rev`](#param-counts_per_rev) | 1/rev *(canonical)* | Lines: a quadrature encoder counts 4 × lines per revolution. |
81
+ | `latency_s` | [`latency`](#param-latency) | s *(canonical)* | |
82
+
83
+ ## Packed names
84
+
85
+ Names for one array that carries several of these parameters; never read as one parameter.
86
+
87
+ None.
88
+
89
+ ## Deployment-only names
90
+
91
+ Names some model reads that are not the type's own: a deployment sets them, or the mount gives them.
92
+
93
+ None.
94
+
95
+ ## References
96
+
97
+ The works the rungs cite, by their names in [`robot_models.references`](../../references.py).
98
+
99
+ - <a id="ref-junker_1969"></a>**JUNKER_1969**: Junker (1969). New criteria for self-loosening of fasteners under vibration. SAE Technical Paper. [doi:10.4271/690055](https://doi.org/10.4271/690055). What the rung uses: a mount loosening under transverse vibration. Cited by [`M2.wear`](#rung-m2-wear).
100
+ - <a id="ref-merry_2010"></a>**MERRY_2010**: Merry, van de Molengraft, Steinbuch (2010). Velocity and acceleration estimation for optical incremental encoders. Mechatronics. [doi:10.1016/j.mechatronics.2009.06.010](https://doi.org/10.1016/j.mechatronics.2009.06.010). What the rung uses: encoder noise, quantisation and delay in velocity. Cited by [`M1.noise_latency`](#rung-m1-noise_latency).
101
+ - <a id="ref-whitmore_1995"></a>**WHITMORE_1995**: Whitmore (1995). Estimating degradation by a Wiener diffusion process subject to measurement error. Lifetime Data Analysis. [doi:10.1007/BF00985762](https://doi.org/10.1007/BF00985762). What the rung uses: diffusive drift: its expected size grows as the square root of time. Cited by [`M2.wear`](#rung-m2-wear).
102
+ - <a id="ref-widrow_2008"></a>**WIDROW_2008**: Widrow, Kollár (2008). Quantization Noise. Cambridge University Press. [doi:10.1017/CBO9780511754661](https://doi.org/10.1017/CBO9780511754661) (book). What the rung uses: an encoder as a quantiser. Cited by [`M0.quantiser`](#rung-m0-quantiser).
103
+ - <a id="ref-zhao_2024"></a>**ZHAO_2024**: Zhao, Wan, Liang (2024). Automatic compensation system for eccentricity error of absolute optical encoder. Review of Scientific Instruments. [doi:10.1063/5.0211297](https://doi.org/10.1063/5.0211297). What the rung uses: eccentricity as once-per-turn harmonics. Cited by [`M2.eccentricity`](#rung-m2-eccentricity).
@@ -0,0 +1,5 @@
1
+ """An angle sensor on a shaft, such as a drive's rotor encoder: its ladder of models (PEP 0004), in `ladder.py`.
2
+
3
+ The type covers any sensor that reports a shaft's angle as a count: it quantises the angle, adds noise and a delay,
4
+ and can carry an angle error that repeats once per turn (an eccentric magnet or disc) that grows as its mount loosens.
5
+ """
@@ -0,0 +1,133 @@
1
+ """An angle sensor on a shaft, such as a drive's rotor encoder: its ladder of models.
2
+
3
+ The reading is the shaft's angle, quantised to counts_per_rev (M0), with noise and a delay (M1), plus an angle error
4
+ that repeats with the shaft angle (M2.eccentricity), which grows over vibration hours as the mount loosens (M2.wear).
5
+
6
+ Spec: PEP 0004 §5.6 and §6.5.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from robot_models import references
12
+ from robot_models.ladder import Alias, Ladder, Parameter, Rung, Wear
13
+
14
+ # --- the vocabulary, grouped by the rung that first reads each name ------------------------------------------------
15
+
16
+ VOCABULARY = (
17
+ # M0.quantiser
18
+ Parameter(
19
+ name="counts_per_rev",
20
+ unit="1/rev",
21
+ shape="integer",
22
+ definition="Distinct readings per revolution of the shaft it reads: its quantisation.",
23
+ ),
24
+ # M1.noise_latency
25
+ Parameter(
26
+ name="noise_sigma",
27
+ unit="rad",
28
+ shape="scalar",
29
+ definition="Standard deviation of the reading's noise at standstill.",
30
+ ),
31
+ Parameter(
32
+ name="latency",
33
+ unit="s",
34
+ shape="scalar",
35
+ definition="Delay from the shaft's angle to the reading that reports it.",
36
+ ),
37
+ # M2.eccentricity
38
+ Parameter(
39
+ name="eccentricity_harmonics",
40
+ unit="rad",
41
+ shape="list",
42
+ definition=("Angle error periodic in the shaft angle (an eccentric magnet or disc), a list of (harmonic, "
43
+ "amplitude, phase)."),
44
+ ),
45
+ # M2.wear
46
+ Parameter(
47
+ name="eccentricity_growth",
48
+ unit="rad/√h",
49
+ shape="scalar",
50
+ definition=("How fast the eccentricity grows with the square root of vibration hours (a loosening "
51
+ "mount)."),
52
+ ),
53
+ )
54
+
55
+ # --- the rungs, M0 upward ------------------------------------------------------------------------------------------
56
+
57
+ RUNGS = (
58
+ Rung(
59
+ level=0,
60
+ name="quantiser",
61
+ title="An ideal quantiser",
62
+ base=None,
63
+ adds=("counts_per_rev",),
64
+ equation="q_reported = round(q/lsb)·lsb, lsb = 2π/counts_per_rev",
65
+ references=(references.WIDROW_2008,),
66
+ ),
67
+ Rung(
68
+ level=1,
69
+ name="noise_latency",
70
+ title="Noise and latency",
71
+ base="M0.quantiser",
72
+ adds=("noise_sigma", "latency"),
73
+ equation="q_reported(t) = round((q(t − latency) + n)/lsb)·lsb, n ~ N(0, noise_sigma²)",
74
+ references=(references.MERRY_2010,),
75
+ ),
76
+ Rung(
77
+ level=2,
78
+ name="eccentricity",
79
+ title="Eccentricity harmonics",
80
+ base="M1.noise_latency",
81
+ adds=("eccentricity_harmonics",),
82
+ equation="q_reported = round((q + e(q) + n)/lsb)·lsb, delayed; e(q) the eccentricity harmonics",
83
+ references=(references.ZHAO_2024,),
84
+ ),
85
+ Rung(
86
+ level=2,
87
+ name="wear",
88
+ title="A mount that loosens over vibration hours",
89
+ base="M2.eccentricity",
90
+ adds=("eccentricity_growth",),
91
+ # WHY square root (PEP 0004 §5.6): a loosening mount drifts diffusively, so the harmonics' expected size grows
92
+ # with the square root of vibration hours (Whitmore 1995) rather than linearly. WHY per amplitude: the
93
+ # harmonics are a list of (harmonic, amplitude, phase); a loosening mount grows the error, not its period.
94
+ wears=(
95
+ Wear(
96
+ parameter="eccentricity_harmonics",
97
+ usage="vibration hours",
98
+ usage_unit="h",
99
+ law="sqrt",
100
+ rate="eccentricity_growth",
101
+ ),
102
+ ),
103
+ equation=("amplitude_k(h) = amplitude_k + eccentricity_growth·√h for each eccentricity harmonic "
104
+ "(its harmonic and phase stay)"),
105
+ references=(references.JUNKER_1969, references.WHITMORE_1995),
106
+ ),
107
+ )
108
+
109
+ # --- other names for the vocabulary (PEP 0004 §6.5) ----------------------------------------------------------------
110
+
111
+ ALIASES = (
112
+ Alias(name="latency_s", canonical="latency"),
113
+ Alias(name="eccentricity_growth_mrad_per_sqrt_h", canonical="eccentricity_growth", unit="mrad/√h"),
114
+ Alias(name="encoder_counts_per_rev", canonical="counts_per_rev"),
115
+ Alias(name="encoder_counts", canonical="counts_per_rev"),
116
+ Alias(
117
+ name="encoder_lines",
118
+ canonical="counts_per_rev",
119
+ note="Lines: a quadrature encoder counts 4 × lines per revolution.",
120
+ ),
121
+ Alias(name="encoder_bits", canonical="counts_per_rev", note="Bits: 2^bits counts per revolution."),
122
+ )
123
+
124
+ # No packed names and no deployment-only names: nothing here packs several quantities into one array, and every
125
+ # quantity the models read belongs to the sensor itself.
126
+
127
+ LADDER = Ladder(
128
+ type="encoder",
129
+ title="An angle sensor on a shaft, such as a drive's rotor encoder.",
130
+ vocabulary=VOCABULARY,
131
+ rungs=RUNGS,
132
+ aliases=ALIASES,
133
+ )
@@ -0,0 +1,107 @@
1
+ > **Generated file.** Written by [`tools/make_type_docs.py`](../../../../tools/make_type_docs.py) from this folder's [`ladder.py`](ladder.py): edit the ladder, not this file, then run `python tools/make_type_docs.py` from the repository root.
2
+
3
+ # hyperspectral_camera
4
+
5
+ A line-scan spectral camera over a belt.
6
+
7
+ **5 rungs** · 7 parameters · 1 aliases · 1 packed names · 0 deployment-only names · folder `sensors/hyperspectral_camera/`.
8
+
9
+ In code: `ladders()["hyperspectral_camera"]` from [`robot_models.ladder`](../../ladder.py). Every type: [docs/TYPES.md](../../../../docs/TYPES.md). Spec: [PEP 0004](../../../../docs/peps/0004-model-ladders-by-type.md).
10
+ Projects the notes below name, and what they are: [sim2real](../../../../docs/TYPES.md#name-sim2real).
11
+
12
+ ## About
13
+
14
+ From the docstring of [`ladder.py`](ladder.py):
15
+
16
+ Each frame is one line of the belt, split into spectral bands; the belt's motion sweeps the lines into a cube. The
17
+ ladder starts at the bands and the references that turn counts into reflectance, then adds the optics' distortion, the
18
+ sweep geometry, and the white reference's drift over deployment hours.
19
+
20
+ Spec: PEP 0004 §5.9 and §6.8.
21
+
22
+ ## The ladder
23
+
24
+ ```mermaid
25
+ flowchart BT
26
+ M0_bands["M0.bands<br/>Ideal spectral bands"]
27
+ M1_band_widths["M1.band_widths<br/>Band widths"]
28
+ M2_smile_keystone["M2.smile_keystone<br/>Smile and keystone"]
29
+ M3_pushbroom["M3.pushbroom<br/>Pushbroom line geometry"]
30
+ M3_wear["M3.wear<br/>A white reference that<br/>drifts with hours"]
31
+ M0_bands --> M1_band_widths
32
+ M1_band_widths --> M2_smile_keystone
33
+ M2_smile_keystone --> M3_pushbroom
34
+ M3_pushbroom --> M3_wear
35
+ classDef physics fill:#e8f1fb,stroke:#2f6aa3,color:#10243a
36
+ classDef wear fill:#e8f1fb,stroke:#2f6aa3,color:#10243a,stroke-dasharray:6 3
37
+ class M0_bands,M1_band_widths,M2_smile_keystone,M3_pushbroom physics
38
+ class M3_wear wear
39
+ ```
40
+
41
+ Read it bottom up: each solid arrow runs from a rung's base to the rung that extends it, and a rung needs everything below it on its own chain (its fallback). Blue box: a physics rung; dashed blue box: a wear rung (a parameter that grows with use).
42
+
43
+ ## Rungs
44
+
45
+ Bottom up. *Needs* is what the rung's model cannot run without, new over its base; *reads when stated* is what it uses when a source states it. A rung needs everything its base needs.
46
+
47
+ | rung | title | base | needs (adds) | reads when stated (optional) | code | equation | references |
48
+ | --- | --- | --- | --- | --- | --- | --- | --- |
49
+ | <a id="rung-m0-bands"></a>`M0.bands` | Ideal spectral bands | — | `band_centres`, `dark_reference`, `white_reference` | — | — | `R(λ) = (DN − dark_reference)/(white_reference − dark_reference), at each band's band_centres` | [BURGER_2011](#ref-burger_2011) |
50
+ | <a id="rung-m1-band_widths"></a>`M1.band_widths` | Band widths | [`M0.bands`](#rung-m0-bands) | `band_fwhm` | — | — | `each band a Gaussian of its band_fwhm about its band_centres` | [BURGER_2011](#ref-burger_2011), [KRUSE_1993](#ref-kruse_1993) |
51
+ | <a id="rung-m2-smile_keystone"></a>`M2.smile_keystone` | Smile and keystone | [`M1.band_widths`](#rung-m1-band_widths) | `smile_keystone_map` | — | — | `the cube resampled through smile_keystone_map, then R(λ) per band` | [MOUROULIS_2000](#ref-mouroulis_2000) |
52
+ | <a id="rung-m3-pushbroom"></a>`M3.pushbroom` | Pushbroom line geometry | [`M2.smile_keystone`](#rung-m2-smile_keystone) | `line_geometry` | — | — | `a line camera swept by the belt: line k sees the belt at k·(belt distance per line)` | [GUPTA_1997](#ref-gupta_1997) |
53
+ | <a id="rung-m3-wear"></a>`M3.wear` | A white reference that drifts with hours<br>wears `white_reference`: see [Wear](#wear) | [`M3.pushbroom`](#rung-m3-pushbroom) | `reference_drift` | — | — | `white_reference(h) = white_reference + reference_drift·h; dark_reference stays` | [LU_MEEKER_1993](#ref-lu_meeker_1993) |
54
+
55
+ ## Wear
56
+
57
+ Which parameter grows with use, with what, by which law, at which rate.
58
+
59
+ | rung | parameter that wears | grows with | law | rate |
60
+ | --- | --- | --- | --- | --- |
61
+ | [`M3.wear`](#rung-m3-wear) | [`white_reference`](#param-white_reference) | deployment hours (h) | linear: `p(u) = p0 + k·u` | [`reference_drift`](#param-reference_drift) |
62
+
63
+ ## Vocabulary
64
+
65
+ Every parameter the ladder holds, by the rung that first reads it. — as a unit: dimensionless (a ratio or a count).
66
+
67
+ | parameter | SI unit | shape | definition | first read on |
68
+ | --- | --- | --- | --- | --- |
69
+ | <a id="param-band_centres"></a>`band_centres` | m | list | Centre wavelength of each spectral band. | [`M0.bands`](#rung-m0-bands) |
70
+ | <a id="param-dark_reference"></a>`dark_reference` | DN | map | The dark reference frame (shutter closed): each pixel's and band's counts at zero light. | [`M0.bands`](#rung-m0-bands) |
71
+ | <a id="param-white_reference"></a>`white_reference` | DN | map | The white reference frame: each pixel's and band's counts over a white tile of known reflectance. | [`M0.bands`](#rung-m0-bands) |
72
+ | <a id="param-band_fwhm"></a>`band_fwhm` | m | list | Full width at half maximum of each band's spectral response. | [`M1.band_widths`](#rung-m1-band_widths) |
73
+ | <a id="param-smile_keystone_map"></a>`smile_keystone_map` | px | map | The spectral (smile) and spatial (keystone) distortion map the cube is resampled with. | [`M2.smile_keystone`](#rung-m2-smile_keystone) |
74
+ | <a id="param-line_geometry"></a>`line_geometry` | m, rad | pair | The scan line's pose, and the belt distance per line. | [`M3.pushbroom`](#rung-m3-pushbroom) |
75
+ | <a id="param-reference_drift"></a>`reference_drift` | DN/h | scalar | How fast the white reference's DN drifts per deployment hour (lamp ageing). The dark reference drifts the other way (dark current) and is not modelled by this rate. | [`M3.wear`](#rung-m3-wear) |
76
+
77
+ ## Aliases
78
+
79
+ Other names a source uses for one of these parameters. A note says how it differs when it is not the same quantity one for one. The unit is the one the source writes its values in; *(canonical)* after it marks an alias stored with no unit of its own, which robot_models reads as the canonical parameter's SI unit, shown here spelled out. A note can still qualify that unit.
80
+
81
+ | alias | canonical | unit | note |
82
+ | --- | --- | --- | --- |
83
+ | `reference_drift_per_h` | [`reference_drift`](#param-reference_drift) | DN/h *(canonical)* | |
84
+
85
+ ## Packed names
86
+
87
+ Names for one array that carries several of these parameters; never read as one parameter.
88
+
89
+ | packed name | carries | order | note |
90
+ | --- | --- | --- | --- |
91
+ | `dark_white_refs` | [`dark_reference`](#param-dark_reference), [`white_reference`](#param-white_reference) | its full entry order | sim2real's camera_hsi card: (dark, white) as its name reads, both in DN. |
92
+
93
+ ## Deployment-only names
94
+
95
+ Names some model reads that are not the type's own: a deployment sets them, or the mount gives them.
96
+
97
+ None.
98
+
99
+ ## References
100
+
101
+ The works the rungs cite, by their names in [`robot_models.references`](../../references.py).
102
+
103
+ - <a id="ref-burger_2011"></a>**BURGER_2011**: Burger, Gowen (2011). Data handling in hyperspectral image analysis. Chemometrics and Intelligent Laboratory Systems. [doi:10.1016/j.chemolab.2011.04.001](https://doi.org/10.1016/j.chemolab.2011.04.001). What the rung uses: dark and white reference reflectance calibration. Cited by [`M0.bands`](#rung-m0-bands), [`M1.band_widths`](#rung-m1-band_widths).
104
+ - <a id="ref-gupta_1997"></a>**GUPTA_1997**: Gupta, Hartley (1997). Linear pushbroom cameras. IEEE Transactions on Pattern Analysis and Machine Intelligence. [doi:10.1109/34.615446](https://doi.org/10.1109/34.615446). What the rung uses: the line-scan (pushbroom) camera's geometry. Cited by [`M3.pushbroom`](#rung-m3-pushbroom).
105
+ - <a id="ref-kruse_1993"></a>**KRUSE_1993**: Kruse, Lefkoff, Boardman, Heidebrecht, Shapiro, Barloon, Goetz (1993). The spectral image processing system (SIPS)—interactive visualization and analysis of imaging spectrometer data. Remote Sensing of Environment. [doi:10.1016/0034-4257(93)90013-N](https://doi.org/10.1016/0034-4257%2893%2990013-N). What the rung uses: the spectral angle. Cited by [`M1.band_widths`](#rung-m1-band_widths).
106
+ - <a id="ref-lu_meeker_1993"></a>**LU_MEEKER_1993**: Lu, Meeker (1993). Using degradation measures to estimate a time-to-failure distribution. Technometrics. [doi:10.1080/00401706.1993.10485038](https://doi.org/10.1080/00401706.1993.10485038). What the rung uses: a degradation path in usage, linear the simplest, crossing a failure threshold. Cited by [`M3.wear`](#rung-m3-wear).
107
+ - <a id="ref-mouroulis_2000"></a>**MOUROULIS_2000**: Mouroulis, Green, Chrien (2000). Design of pushbroom imaging spectrometers for optimum recovery of spectroscopic and spatial information. Applied Optics. [doi:10.1364/AO.39.002210](https://doi.org/10.1364/AO.39.002210). What the rung uses: smile and keystone. Cited by [`M2.smile_keystone`](#rung-m2-smile_keystone).
@@ -0,0 +1 @@
1
+ """A line-scan (pushbroom) spectral camera over a belt; its ladder of models is `ladder.py` (PEP 0004 §5.9)."""