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.
- robot_models/__init__.py +18 -0
- robot_models/actuators/__init__.py +1 -0
- robot_models/actuators/rungs/README.md +24 -0
- robot_models/actuators/rungs/coulomb_viscous/README.md +61 -0
- robot_models/actuators/rungs/coulomb_viscous/model.js +14 -0
- robot_models/actuators/rungs/coulomb_viscous/model.json +102 -0
- robot_models/actuators/rungs/coulomb_viscous/model.py +24 -0
- robot_models/actuators/rungs/datasheet/README.md +65 -0
- robot_models/actuators/rungs/datasheet/model.js +14 -0
- robot_models/actuators/rungs/datasheet/model.json +138 -0
- robot_models/actuators/rungs/datasheet/model.py +24 -0
- robot_models/actuators/rungs/dcmotor/README.md +63 -0
- robot_models/actuators/rungs/dcmotor/model.json +163 -0
- robot_models/actuators/rungs/ideal/README.md +60 -0
- robot_models/actuators/rungs/ideal/model.js +6 -0
- robot_models/actuators/rungs/ideal/model.json +90 -0
- robot_models/actuators/rungs/ideal/model.py +13 -0
- robot_models/actuators/rungs/load/README.md +65 -0
- robot_models/actuators/rungs/load/model.js +15 -0
- robot_models/actuators/rungs/load/model.json +117 -0
- robot_models/actuators/rungs/load/model.py +25 -0
- robot_models/actuators/rungs/lugre/README.md +72 -0
- robot_models/actuators/rungs/lugre/model.js +24 -0
- robot_models/actuators/rungs/lugre/model.json +164 -0
- robot_models/actuators/rungs/lugre/model.py +30 -0
- robot_models/actuators/rungs/ripple/README.md +64 -0
- robot_models/actuators/rungs/ripple/model.js +17 -0
- robot_models/actuators/rungs/ripple/model.json +119 -0
- robot_models/actuators/rungs/ripple/model.py +27 -0
- robot_models/actuators/rungs/stribeck/README.md +65 -0
- robot_models/actuators/rungs/stribeck/model.js +17 -0
- robot_models/actuators/rungs/stribeck/model.json +126 -0
- robot_models/actuators/rungs/stribeck/model.py +28 -0
- robot_models/actuators/servo/README.md +278 -0
- robot_models/actuators/servo/__init__.py +7 -0
- robot_models/actuators/servo/bldc/README.md +186 -0
- robot_models/actuators/servo/bldc/__init__.py +5 -0
- robot_models/actuators/servo/bldc/bldc_motor.py +93 -0
- robot_models/actuators/servo/bldc/ladder.py +268 -0
- robot_models/actuators/servo/foc_controller/README.md +127 -0
- robot_models/actuators/servo/foc_controller/__init__.py +3 -0
- robot_models/actuators/servo/foc_controller/ladder.py +207 -0
- robot_models/actuators/servo/gearbox/README.md +148 -0
- robot_models/actuators/servo/gearbox/__init__.py +5 -0
- robot_models/actuators/servo/gearbox/gearbox.py +36 -0
- robot_models/actuators/servo/gearbox/ladder.py +214 -0
- robot_models/actuators/servo/integrated_servo.py +33 -0
- robot_models/actuators/servo/ladder.py +593 -0
- robot_models/arms/__init__.py +1 -0
- robot_models/arms/rigid_body_chain/README.md +151 -0
- robot_models/arms/rigid_body_chain/__init__.py +3 -0
- robot_models/arms/rigid_body_chain/ladder.py +228 -0
- robot_models/conveyors/__init__.py +1 -0
- robot_models/conveyors/conveyor/README.md +140 -0
- robot_models/conveyors/conveyor/__init__.py +1 -0
- robot_models/conveyors/conveyor/ladder.py +203 -0
- robot_models/datasheet/__init__.py +56 -0
- robot_models/datasheet/datasheet.py +355 -0
- robot_models/datasheet/literal.py +144 -0
- robot_models/datasheet/source.py +328 -0
- robot_models/datasheet/stated.py +135 -0
- robot_models/datasheet/units.py +57 -0
- robot_models/end_effectors/__init__.py +1 -0
- robot_models/end_effectors/gripper/README.md +112 -0
- robot_models/end_effectors/gripper/__init__.py +3 -0
- robot_models/end_effectors/gripper/ladder.py +150 -0
- robot_models/homing/__init__.py +38 -0
- robot_models/homing/cad_bundle.py +206 -0
- robot_models/homing/contact.py +201 -0
- robot_models/homing/fit.py +126 -0
- robot_models/homing/metrics.py +237 -0
- robot_models/homing/protocols.py +72 -0
- robot_models/homing/types.py +256 -0
- robot_models/ladder.py +645 -0
- robot_models/markers/__init__.py +1 -0
- robot_models/markers/aruco_marker/README.md +92 -0
- robot_models/markers/aruco_marker/__init__.py +2 -0
- robot_models/markers/aruco_marker/ladder.py +142 -0
- robot_models/references.py +429 -0
- robot_models/sensors/__init__.py +1 -0
- robot_models/sensors/camera/README.md +118 -0
- robot_models/sensors/camera/__init__.py +3 -0
- robot_models/sensors/camera/ladder.py +108 -0
- robot_models/sensors/encoder/README.md +103 -0
- robot_models/sensors/encoder/__init__.py +5 -0
- robot_models/sensors/encoder/ladder.py +133 -0
- robot_models/sensors/hyperspectral_camera/README.md +107 -0
- robot_models/sensors/hyperspectral_camera/__init__.py +1 -0
- robot_models/sensors/hyperspectral_camera/ladder.py +151 -0
- robot_models/sensors/rgbd/README.md +113 -0
- robot_models/sensors/rgbd/__init__.py +5 -0
- robot_models/sensors/rgbd/ladder.py +113 -0
- robot_models_lib-0.2.0.dist-info/METADATA +143 -0
- robot_models_lib-0.2.0.dist-info/RECORD +96 -0
- robot_models_lib-0.2.0.dist-info/WHEEL +4 -0
- 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)."""
|