dynos-adaptive-resampling 0.1.2__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.
@@ -0,0 +1,8 @@
1
+ """Adaptive resampling extension for DYNOS Sentry surveys.
2
+
3
+ Adds a resample_zone transition that generates a new survey zone from
4
+ ML model predictions based on historic survey data. Designed to be
5
+ chained after a standard coverage survey.
6
+
7
+ Example stub, modify as you wish.
8
+ """
@@ -0,0 +1,40 @@
1
+ """Adaptive resampling domain extension.
2
+
3
+ Adds vocabulary for ML-driven zone resampling to the Sentry domain.
4
+ This module defines the transition, fluents, and parameters that describe
5
+ the resampling capability. It does NOT contain the ML model itself;
6
+ that lives in the action implementation (robot class).
7
+
8
+ Import this alongside the sentry domain::
9
+
10
+ from dynos_sentry.sentry import phase_ascending, Zone, full_coverage_of
11
+ from dynos_adaptive_resampling.domain import resample_zone, resampling_complete
12
+ """
13
+
14
+ from dynos_client.domain import (
15
+ Transition,
16
+ TransitionParams,
17
+ make_new_fluent,
18
+ )
19
+
20
+ from dynos_sentry.sentry import Zone
21
+
22
+ resampling_complete = make_new_fluent(default=False)
23
+
24
+ class ResampleZoneParams(TransitionParams):
25
+ """Parameters for the resample_zone transition.
26
+
27
+ source_zone: the zone that was just surveyed
28
+ """
29
+ source_zone: Zone
30
+ #confidence: Float # You can add other things if you need to, just don't mess with Zone since the backend needs it to figure out what tracklines to draw
31
+
32
+ resample_zone = Transition(
33
+ params_type=ResampleZoneParams,
34
+ )
35
+
36
+ resample_zone.define(
37
+ preconditions=[],
38
+ adds=[resampling_complete()],
39
+ removes=[],
40
+ )
@@ -0,0 +1,52 @@
1
+ """Example mission: standard survey followed by adaptive resampling.
2
+
3
+ This file shows how to build a mission that chains a coverage survey
4
+ with an ML-driven resampling step. It can be executed against either
5
+ a local or remote backend.
6
+
7
+ Usage::
8
+
9
+ from dynos_adaptive_resampling.mission import build_resample_mission
10
+ from dynos_client import RemoteOrchestrator
11
+
12
+ orch = RemoteOrchestrator("http://backend:8421")
13
+ mission = build_resample_mission("site_alpha")
14
+ results = mission.execute(orch)
15
+ """
16
+
17
+ from dynos_client import Mission
18
+ from dynos_sentry.sentry import full_coverage_of
19
+ from dynos_adaptive_resampling.domain import resample_zone, ResampleZoneParams
20
+
21
+
22
+ def build_resample_mission(zone_name: str) -> Mission:
23
+ """Build a mission: survey zone -> resample -> survey new zone -> abort.
24
+
25
+ Args:
26
+ zone_name: name of the initial survey zone (must already exist
27
+ as a domain object on the backend)
28
+
29
+ Returns:
30
+ A Mission object ready for execution
31
+ """
32
+ mission = Mission(name=f"adaptive_survey_{zone_name}")
33
+
34
+ # Phase 1: initialize the vehicle
35
+ mission.add_action("takeover_control")
36
+
37
+ # Phase 2: survey the original zone
38
+ mission.add_plan([full_coverage_of(zone_name)])
39
+
40
+ # Phase 3: run the ML resampler
41
+ mission.add_action(
42
+ resample_zone,
43
+ params=ResampleZoneParams(source_zone=zone_name),
44
+ )
45
+
46
+ # Phase 4: survey the resampled zone
47
+ mission.add_plan([full_coverage_of(f"resampled_{zone_name}")])
48
+
49
+ # Phase 5: abort and recover
50
+ mission.add_action("full_abort") # specifying steps as strings is not preferred but does work when you don't have the backend implelementation.
51
+
52
+ return mission
@@ -0,0 +1,146 @@
1
+ """Adaptive resampling robot class.
2
+
3
+ This is the action implementation that runs the ML model and creates
4
+ a new survey zone. It is registered with the Orchestrator alongside
5
+ the standard Sentry robot class.
6
+
7
+ STUB: replace the ML model placeholder with your trained model.
8
+
9
+ Usage with a remote backend::
10
+
11
+ from dynos_adaptive_resampling.resampler import AdaptiveResampler
12
+ from dynos_adaptive_resampling.domain import resample_zone
13
+
14
+ # In your Runnable.register():
15
+ orchestrator.register_class(AdaptiveResampler)
16
+ """
17
+
18
+ from typing import Any, Dict, List, Optional
19
+
20
+ # vvv Recommended that you don't touch any of this vvv
21
+ from dynos_client.domain import ObjectType, SymbolicObject, ValueField, make_new_object
22
+ from dynos_adaptive_resampling.domain import resample_zone, ResampleZoneParams
23
+
24
+ try:
25
+ from dynos.databases.typed_action import Action
26
+ except ImportError:
27
+ from dynos_client.action import Action # type: ignore
28
+
29
+ # ^^^ Recommended you don't touch any of this ^^^
30
+
31
+ # Edit away down here
32
+ class ZoneProposal:
33
+ """A proposed survey zone from the ML model. Modify as needed (except as noted)
34
+
35
+ Attributes:
36
+ vertices: list of (latitude, longitude) tuples
37
+ altitude: survey altitude in meters
38
+ speed: survey speed in m/s
39
+ confidence: model confidence (0.0:1.0)
40
+ """
41
+
42
+ def __init__(
43
+ self,
44
+ vertices: List[tuple],
45
+ altitude: float = 70.0,
46
+ speed: float = 0.8,
47
+ confidence: float = 0.0,
48
+ ):
49
+ self.vertices = vertices # need
50
+ self.altitude = altitude # need, but can be overridden during execution by the operator
51
+ self.speed = speed # need, but can be overridden during execution by the operator
52
+ self.confidence = confidence # don't need, not used internally, feel free to add this or other things if helpful
53
+
54
+
55
+ class AdaptiveResampler:
56
+ """Robot class that implements ML-driven zone resampling.
57
+
58
+ Register this alongside the standard Sentry robot class::
59
+
60
+ orchestrator.register_class(SentryMock)
61
+ orchestrator.register_class(AdaptiveResampler)
62
+
63
+ The ``resample_zone`` action:
64
+ 1. Reads historic survey data from the source zone
65
+ 2. "Runs" the ML model to predict high-interest regions
66
+ 3. Creates a new Zone object with the predicted vertices
67
+ 4. Returns success with the new zone name in telemetry
68
+
69
+ STUB: the ``_predict_new_zone`` method returns a
70
+ hardcoded rectangle that should be replaced with the
71
+ method of selecting the new zone (or zones).
72
+ """
73
+
74
+ def __init__(self):
75
+ self._model = None # Replace with your ML model
76
+ self._prediction_history: List[ZoneProposal] = []
77
+
78
+ @Action(transition=resample_zone)
79
+ def do_resample(self, params: ResampleZoneParams, ctx) -> dict:
80
+ """Execute the resampling action. Sample implementation.
81
+
82
+ Args:
83
+ params: ResampleZoneParams with source_zone
84
+ ctx: ActionContext (provides logging, config)
85
+
86
+ Returns:
87
+ ActionResult-compatible dict with success status and telemetry
88
+ """
89
+ source_zone_name = str(params.source_zone)
90
+
91
+ historic_data = self._gather_historic_data(source_zone_name)
92
+ proposal = self._predict_new_zone(historic_data)
93
+ self._prediction_history.append(proposal)
94
+
95
+ # The new zone is created at runtime via the orchestrator (or remote orchestrator):
96
+ #
97
+ # remote_orch.create_object(
98
+ # type_name="zone",
99
+ # name=f"resampled_{source_zone_name}",
100
+ # vertices=proposal.vertices,
101
+ # altitude=proposal.altitude,
102
+ # speed=proposal.speed,
103
+ # )
104
+
105
+ new_zone_name = f"resampled_{source_zone_name}"
106
+
107
+ return {
108
+ "success": True,
109
+ "telemetry": {
110
+ "new_zone": new_zone_name,
111
+ "vertices": proposal.vertices,
112
+ "confidence": proposal.confidence,
113
+ "source_zone": source_zone_name,
114
+ },
115
+ } # Telemetery isn't used for anything internally, it's just for logging so edit away. 'success' param matters though: if false, we'll try again or eventually give up.
116
+
117
+ def _gather_historic_data(self, zone_name: str) -> Dict[str, Any]:
118
+ """Gather historic survey data for a zone.
119
+
120
+ STUB: returns empty data in a format we don't care about on the backend.
121
+ """
122
+ return {
123
+ "zone_name": zone_name,
124
+ "tracklines_completed": 0,
125
+ "sonar_readings": [],
126
+ "anomalies_detected": [],
127
+ }
128
+
129
+ def _predict_new_zone(self, historic_data: Dict[str, Any]) -> ZoneProposal:
130
+ """Run the ML model to predict a high-interest zone.
131
+
132
+ STUB: returns a hardcoded rectangle offset from the original zone.
133
+
134
+ Your model should return a polygon (list of lat/lon vertices) defining the new zone
135
+ """
136
+ return ZoneProposal(
137
+ vertices=[
138
+ (41.0, -70.0),
139
+ (41.0, -69.9),
140
+ (41.1, -69.9),
141
+ (41.1, -70.0),
142
+ ],
143
+ altitude=70.0,
144
+ speed=0.8,
145
+ confidence=0.5,
146
+ )
@@ -0,0 +1,41 @@
1
+ """Runnable for the adaptive resampling extension.
2
+
3
+ This is the entry point for ``dynos connect``. It registers the
4
+ AdaptiveResampler robot class alongside any existing Sentry classes
5
+ on the local orchestrator, then the servant loop handles the rest.
6
+
7
+ Usage::
8
+
9
+ dynos connect dynos_adaptive_resampling.runnable:AdaptiveResamplingNode \\
10
+ --to http://backend:8421
11
+ """
12
+
13
+ from typing import List
14
+
15
+
16
+ class AdaptiveResamplingNode:
17
+ """Runnable that provides the adaptive resampling action to a remote backend.
18
+
19
+ This registers ``AdaptiveResampler`` so that the ``resample_zone``
20
+ transition can be executed on this hardware node. The standard
21
+ Sentry actions (fly_trackline, etc.) are handled by a separate
22
+ servant node running the Sentry hardware class.
23
+
24
+ This is a standardized format that the backend expects.
25
+ It shouldn't be necessary for you to modify this.
26
+ """
27
+
28
+ @staticmethod
29
+ def register(orchestrator, cli):
30
+ from dynos_adaptive_resampling.resampler import AdaptiveResampler
31
+ orchestrator.register_class(AdaptiveResampler)
32
+
33
+ @staticmethod
34
+ def get_start_state(cli) -> List:
35
+ # No initial state; the backend already has the mission state
36
+ return []
37
+
38
+ @staticmethod
39
+ def get_start_goal(cli) -> List:
40
+ # No default goal; the backend sets the mission goal
41
+ return []
@@ -0,0 +1,190 @@
1
+ Metadata-Version: 2.1
2
+ Name: dynos-adaptive-resampling
3
+ Version: 0.1.2
4
+ Summary: Adaptive resampling extension for DYNOS Sentry surveys
5
+ License: Apache-2.0
6
+ Requires-Python: >=3.8
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: dynos-client >=0.1.2
9
+ Requires-Dist: dynos-sentry-domain ==0.1.2
10
+ Requires-Dist: numpy
11
+ Provides-Extra: dev
12
+ Requires-Dist: pytest ; extra == 'dev'
13
+
14
+ # dynos-adaptive-resampling
15
+
16
+ A worked example: chain an ML-driven resampling step onto a Sentry survey. This
17
+ package is scaffolding: it ships a stub `AdaptiveResampler` that you
18
+ replace with your model, plus the wiring (`runnable.py`, `mission.py`) that
19
+ lets `dynos connect` find it and that lets the planner sequence "survey,
20
+ resample, resurvey".
21
+
22
+ The package contributes one new transition (`resample_zone`) and one new
23
+ mission template (`build_resample_mission`). Everything else is for you to
24
+ edit.
25
+
26
+ ## Install
27
+
28
+ You will be modifying the source, so install editable:
29
+
30
+ ```bash
31
+ pip install -e dynos-adaptive-resampling
32
+ ```
33
+
34
+ This pulls in `dynos-client`, `dynos-sentry-domain`, and `numpy`.
35
+
36
+ ## What's in this repository
37
+
38
+ ### `domain.py`
39
+
40
+ Declares `resample_zone` (transition), `ResampleZoneParams` (its parameter
41
+ dataclass), `resampling_complete` (a fluent the transition adds). Edit if
42
+ you need new fluents or parameters.
43
+
44
+ ### `resampler.py`
45
+
46
+ Provides `AdaptiveResampler` class with `@Action(transition=resample_zone)`.
47
+ Edit `_gather_historic_data` and `_predict_new_zone` or whatever else you
48
+ need to get your model integrated.
49
+
50
+ ### `mission.py`
51
+
52
+ Provides `build_resample_mission(zone_name)` returns a `Mission` that does
53
+ survey, resample, resurvey. Edit If you want a different sequence.
54
+
55
+ ### `runnable.py`
56
+
57
+ Provides `AdaptiveResamplingNode`, the `dynos connect`-compatible entry point.
58
+ You probably don't need to edit this.
59
+
60
+ ## How the round-trip works
61
+
62
+ 1. You launch the resampler as a servant: `dynos connect
63
+ dynos_adaptive_resampling.runnable:AdaptiveResamplingNode`. The servant
64
+ idles, polling the backend for assignments.
65
+ 2. From a second terminal you build the mission and call `execute_blocks`. The
66
+ first plan block surveys the source zone end-to-end.
67
+ 3. The planner reaches `resample_zone(source_zone=site_alpha)`. It dispatches
68
+ the assignment over HTTP to your servant.
69
+ 4. Your `AdaptiveResampler` runs `_gather_historic_data`, then
70
+ `_predict_new_zone`, then writes the resulting `ZoneProposal` back as a new
71
+ `Zone` object on the backend.
72
+ 5. The next plan block surveys the new zone. The mission ends with abort +
73
+ recover.
74
+
75
+ ## Replacing the stub
76
+
77
+ You will edit two methods in `resampler.py`:
78
+
79
+ `_gather_historic_data(zone_name)`: return whatever your model needs. The
80
+ shipped stub returns an empty dict; you replace it with calls to a shared
81
+ database, ROS bag, the backend API (`orch.get_objects(type="zone")`), an
82
+ offline NetCDF, etc.
83
+
84
+ `_predict_new_zone(historic_data)`: return a `ZoneProposal` with
85
+ `vertices`, `altitude`, `speed`, and `confidence`:
86
+
87
+ ```python
88
+ def _predict_new_zone(self, historic_data):
89
+ features = self._extract_features(historic_data["sonar_readings"])
90
+ prediction = self._model.predict(features)
91
+ return ZoneProposal(
92
+ vertices=self._prediction_to_polygon(prediction),
93
+ altitude=70.0,
94
+ speed=0.8,
95
+ confidence=float(prediction.confidence),
96
+ )
97
+ ```
98
+
99
+ You can add fields to `ResampleZoneParams` (e.g. a confidence threshold, or
100
+ whatever else you want), but don't change the `Zone` parameter: the backend's
101
+ coverage planner reads `Zone.vertices`, `Zone.coverage_width`, etc. to draw
102
+ tracklines, and it expects the public schema.
103
+
104
+ ## Test offline
105
+
106
+ Before pointing at the real backend, run the package's own tests:
107
+
108
+ ```bash
109
+ pip install -e "dynos-adaptive-resampling/[dev]"
110
+ pytest dynos-adaptive-resampling/tests/ -v
111
+ ```
112
+
113
+ These exercise `_gather_historic_data` and `_predict_new_zone` against a stub
114
+ backend. No network or session needed.
115
+
116
+ ## Run it for real
117
+
118
+ Two terminals.
119
+
120
+ Terminal 1 is your resampler. This can be your laptop, a lab server, or the
121
+ same machine as the backend; the backend dispatches each assignment to
122
+ whichever servant is currently registered for `resample_zone`.
123
+
124
+ ```bash
125
+ dynos login # logins persist across terminals but expire after an hour
126
+ dynos session create
127
+ dynos connect dynos_adaptive_resampling.runnable:AdaptiveResamplingNode
128
+ ```
129
+
130
+ Leave it running. It executes `resample_zone` whenever the backend reaches that
131
+ step.
132
+
133
+ Terminal 2 is mission. Create the source zone and run the adaptive mission:
134
+
135
+ ```bash
136
+ dynos call create zone.json
137
+ ```
138
+
139
+ ```python
140
+ from dynos_client import RemoteOrchestrator
141
+ from dynos_adaptive_resampling.mission import build_resample_mission
142
+
143
+ orch = RemoteOrchestrator.from_config(timeout_s=3600)
144
+ results = orch.execute_blocks(build_resample_mission("site_alpha"))
145
+ for r in results:
146
+ print(r)
147
+ ```
148
+
149
+ While it runs, monitor from a third terminal:
150
+
151
+ ```bash
152
+ dynos call state --scope public # current symbolic state, pruned only for the symbols you're expecting
153
+ dynos call goal # current goal
154
+ dynos call objects --type zone # source + proposed zones
155
+ ```
156
+
157
+ ## What the mission does, step by step
158
+
159
+ 1. Init. Takeover, descent, mode setup.
160
+ 2. Survey the source zone (`full_coverage_of(site_alpha)`).
161
+ 3. Resample. Plan dispatches `resample_zone(source_zone=site_alpha)` to your servant; your model creates `resampled_site_alpha`.
162
+ 4. Resurvey. `full_coverage_of(resampled_site_alpha)`.
163
+ 5. Recover. Abort and ascend.
164
+
165
+ ## Public API
166
+
167
+ | Symbol | From | Purpose |
168
+ |-------------------------------------|---------------------------------------|------------------------------------------------|
169
+ | `resample_zone` | `dynos_adaptive_resampling.domain` | The transition that fires your `@Action`. |
170
+ | `ResampleZoneParams` | `dynos_adaptive_resampling.domain` | Its parameter dataclass (`source_zone: Zone`). |
171
+ | `resampling_complete` | `dynos_adaptive_resampling.domain` | Fluent the transition adds. |
172
+ | `AdaptiveResampler` | `dynos_adaptive_resampling.resampler` | The class you edit. |
173
+ | `AdaptiveResamplingNode` | `dynos_adaptive_resampling.runnable` | The `dynos connect` entry point. |
174
+ | `build_resample_mission(zone_name)` | `dynos_adaptive_resampling.mission` | Survey, resample, resurvey. |
175
+
176
+ ## Troubleshooting
177
+
178
+ Resampler never gets an assignment: The mission hasn't reached `resample_zone`
179
+ yet. Check `dynos call state --scope public`.
180
+
181
+ `No plan found`: The source zone doesn't exist, has no `vertices`, or has
182
+ `coverage_width <= 0`. Check `dynos call objects --type zone`.
183
+
184
+ Resurvey failed: The proposed zone is missing fields. `resampled_*` needs
185
+ `vertices` (3+), `coverage_width > 0`, `robot_width > 0`, and
186
+ `coordinate_frame`. The `ZoneProposal` dataclass populates these; if you
187
+ bypassed it, double-check.
188
+
189
+ For cross-package issues (login, session, connection), see `user_guide.md` or
190
+ `dynos-client`'s README.
@@ -0,0 +1,9 @@
1
+ dynos_adaptive_resampling/__init__.py,sha256=KcyxstlRErJaqGZQnQ5Z3hZmfv-ge73981jYXy8AQzE,278
2
+ dynos_adaptive_resampling/domain.py,sha256=4x52vFbhRFjuuRwpa2ErD8tQCfi9t2c0HST9oiUnG3M,1201
3
+ dynos_adaptive_resampling/mission.py,sha256=hH7M7cS2g-WzhFpa0Rx_uaoUtz4ggQ4depLODulF00g,1704
4
+ dynos_adaptive_resampling/resampler.py,sha256=U7WrkUwGxHR_LRbHzDH4y1s6CtCMX9fvCKkg6WUsgPI,5202
5
+ dynos_adaptive_resampling/runnable.py,sha256=aXPBql0ec2WQXe5ef1XOfWpvGloNq2mC5yuHOYnMPnc,1364
6
+ dynos_adaptive_resampling-0.1.2.dist-info/METADATA,sha256=pYLQSHoAHXR_jekrn8-GuRhQ5ZnMS_dtHu4bZby2FOA,7128
7
+ dynos_adaptive_resampling-0.1.2.dist-info/WHEEL,sha256=BNRMDyzLkkcmlv0J8ppDQkk2VED33SesJDynr9ED1gc,91
8
+ dynos_adaptive_resampling-0.1.2.dist-info/top_level.txt,sha256=mUMKLWIXOwX200dzYJYYqv4D6MS0xFI1dnxg0Ma5be0,26
9
+ dynos_adaptive_resampling-0.1.2.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (75.3.4)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1 @@
1
+ dynos_adaptive_resampling