seavision-python 0.1.1__tar.gz → 0.1.2__tar.gz

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 (79) hide show
  1. {seavision_python-0.1.1 → seavision_python-0.1.2}/PKG-INFO +110 -115
  2. seavision_python-0.1.2/README.md +226 -0
  3. {seavision_python-0.1.1 → seavision_python-0.1.2}/pyproject.toml +1 -1
  4. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/__init__.py +1 -1
  5. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/source/discovery.py +3 -3
  6. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision_python.egg-info/PKG-INFO +110 -115
  7. seavision_python-0.1.1/README.md +0 -231
  8. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/defaults.py +0 -0
  9. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/edge/__init__.py +0 -0
  10. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/edge/bundle.py +0 -0
  11. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/edge/capture.py +0 -0
  12. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/edge/config.py +0 -0
  13. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/edge/postprocess.py +0 -0
  14. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/edge/runtime.py +0 -0
  15. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/edge/writer.py +0 -0
  16. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/__init__.py +0 -0
  17. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/__init__.py +0 -0
  18. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/base.py +0 -0
  19. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/motion/__init__.py +0 -0
  20. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/motion/background.py +0 -0
  21. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/motion/detector.py +0 -0
  22. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/motion/stabiliser.py +0 -0
  23. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/motion/tracker.py +0 -0
  24. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/sam3/__init__.py +0 -0
  25. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/sam3/config.py +0 -0
  26. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/sam3/detector.py +0 -0
  27. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/sam3/native.py +0 -0
  28. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/yolo/__init__.py +0 -0
  29. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/yolo/config.py +0 -0
  30. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/detectors/yolo/detector.py +0 -0
  31. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/export/__init__.py +0 -0
  32. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/export/config.py +0 -0
  33. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/export/exporter.py +0 -0
  34. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/export/validation.py +0 -0
  35. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/postprocessor.py +0 -0
  36. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/source/__init__.py +0 -0
  37. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/source/base.py +0 -0
  38. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/source/local.py +0 -0
  39. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/source/s3.py +0 -0
  40. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/visualiser/__init__.py +0 -0
  41. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/visualiser/annotator.py +0 -0
  42. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/visualiser/config.py +0 -0
  43. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/visualiser/loader.py +0 -0
  44. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/visualiser/visualiser.py +0 -0
  45. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/engine/visualiser/writer.py +0 -0
  46. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/__init__.py +0 -0
  47. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/app.py +0 -0
  48. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/main_window.py +0 -0
  49. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/shared/__init__.py +0 -0
  50. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/shared/conversion.py +0 -0
  51. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/shared/session_utils.py +0 -0
  52. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/__init__.py +0 -0
  53. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/button_styles.py +0 -0
  54. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/detection_detail.py +0 -0
  55. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/detection_rect_item.py +0 -0
  56. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/detection_table.py +0 -0
  57. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/interactive_frame_scene.py +0 -0
  58. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/interactive_frame_view.py +0 -0
  59. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/s3_browser.py +0 -0
  60. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/seekable_source.py +0 -0
  61. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/session.py +0 -0
  62. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/tab.py +0 -0
  63. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/transport_bar.py +0 -0
  64. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/validation_model.py +0 -0
  65. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/video_cache.py +0 -0
  66. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/video_list.py +0 -0
  67. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/video_viewer.py +0 -0
  68. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/gui/validation/video_worker.py +0 -0
  69. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/pipeline.py +0 -0
  70. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/resources/default.yaml +0 -0
  71. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/run_edge.py +0 -0
  72. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/run_export.py +0 -0
  73. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision/run_pipeline.py +0 -0
  74. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision_python.egg-info/SOURCES.txt +0 -0
  75. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision_python.egg-info/dependency_links.txt +0 -0
  76. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision_python.egg-info/entry_points.txt +0 -0
  77. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision_python.egg-info/requires.txt +0 -0
  78. {seavision_python-0.1.1 → seavision_python-0.1.2}/seavision_python.egg-info/top_level.txt +0 -0
  79. {seavision_python-0.1.1 → seavision_python-0.1.2}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: seavision-python
3
- Version: 0.1.1
3
+ Version: 0.1.2
4
4
  Summary: Human-in-the-loop Computer Vision for Marine Environments
5
5
  Author: Mario Lambrette
6
6
  License: Proprietary
@@ -69,53 +69,85 @@ Requires-Dist: twine>=5.1; extra == "dev"
69
69
  > and current CLI behavior as the source of truth until the docs are refreshed.
70
70
 
71
71
  SeaVision offers a practical computer vision workflow for marine monitoring. It supports the development of accurate,
72
- custom detection models for specific deployment scenarios. The main workflow is:
73
-
74
- 1. Deploy a generic detector (e.g. motion detection, SAM3-based semantic detection, etc.) on recorded footage.
75
- 2. Use the provided GUI to validate and refine detections into a training dataset.
76
- 3. Train a custom YOLO detection model.
77
- 4. Deploy the trained model on a desktop workstation or edge device with the provided export functionality.
72
+ custom detection models for specific deployment scenarios. A typical SeaVision
73
+ workflow involves:
74
+
75
+ 1. Record marine monitoring footage
76
+ - This footage can be recorded to a hard drive, stored directly on a
77
+ workstation or stored in an [S3 bucket](https://en.wikipedia.org/wiki/Amazon_S3)
78
+ in the cloud.
79
+
80
+ 2. Process the footage with a generalisable detector.
81
+ - This first-pass processing uses a coarse, generalisable detector that
82
+ returns candiate detections for manual review.
83
+ - Currently implemented detectors include [SAM3](https://ai.meta.com/research/sam3/)-based semantic detection,
84
+ motion detection, and the [Community Fish Detector](https://github.com/filippovarini/community-fish-detector)
85
+
86
+ 3. Use the [SeaVision GUI](TODO: Link to GUI docs) to review the output of the
87
+ generalisable detector.
88
+ - The GUI is used for validation (i.e. how accurate is the generalisable
89
+ detector on my footage?) and for generating training data.
90
+
91
+ 4. Train a custom model using the GUI outputs
92
+ - Annotations made in the GUI can be exported and [converted to YOLO format](TODO: docs for converting SeaVision detections o YOLO format).
93
+ - These annotations can be used to train a custom YOLO detection model with
94
+ the ultralytics framework. See [here](https://docs.ultralytics.com/modes/train/) for details.
95
+ - Model training within SeaVision is not currently supported as the ultralytics
96
+ API abstracts most complexity already.
97
+
98
+ 5. Deploy the trained detection model on recorded and furture footage.
99
+ - The trained YOLO model can be deployed using the SeaVision frameowrk by using
100
+ the YOLODetector class.
101
+ - Users can deploy the model on a worstation, on the cloud or onto an edge
102
+ device.
78
103
 
79
104
  If you are new to the project, start with the [Start Here guide](./docs/Start_Here.md).
80
105
 
81
- ## Start Here (New Users)
82
-
83
- If you are not a computer vision specialist, use this short path first:
84
-
85
- 1. Read the [Start Here guide](./docs/Start_Here.md) for a plain-language workflow and glossary.
86
- 2. Install SeaVision in GUI mode: `python -m pip install ".[gui]"`.
87
- 3. Run `seavision-gui` and create a new session with `Ctrl+N`.
88
- 4. Follow the GUI [Getting Started guide](./docs/gui/Getting%20started.md).
89
-
90
106
  ## Installation
91
107
 
92
108
  ### Prerequisites
93
109
 
94
- - Python 3.12
110
+ - Python 3.10-3.12
95
111
  - pip
112
+ - SeaVision is currently only tested on Windows and Linux systems. Installations
113
+ on MacOS have not been thouroughly tested though may work in certain
114
+ circumstances
96
115
 
97
- ### Install from a cloned repository
116
+ ### Install with pip
98
117
 
99
- Before installing the package, you must currently clone this repository. Run the following in a
100
- bash terminal:
118
+ SeaVision can be installed using pip in a suitable python environemnt.
101
119
 
120
+ #### Conda
121
+ For conda users:
102
122
  ```bash
103
- git clone https://github.com/mariolambrette/SeaVision
104
- cd SeaVision
123
+ conda create -n seavision python=3.11
124
+ conda activate seavision
125
+ python -m pip install --upgrade pip
105
126
  ```
106
127
 
107
- It is recommended to install SeaVision in a dedicated environment. If you are a [conda](https://www.anaconda.com/docs/getting-started/anaconda/install/overview) user, run
108
- the following:
128
+ #### Venv (Windows)
129
+ For windows users without conda run the following in a powershell terminal:
130
+ ```bash
131
+ py -3.11 -m venv .venv-seavision
132
+ .\.venv-seavision\Scripts\Activate.ps1
133
+ python -m pip install --upgrade pip
134
+ ```
109
135
 
136
+ #### Venv (Linux)
137
+ In Linux, without conda, run the following:
110
138
  ```bash
111
- conda create seavision
112
- conda activate seavision
139
+ python3.11 -m venv .venv-seavision
140
+ source .venv-seavision/bin/activate1
141
+ python -m pip install --upgrade pip
113
142
  ```
114
143
 
115
- You can now install SeaVision using pip:
144
+ *NB: python versions 3.10 and 3.12 will also work*
145
+
146
+ #### Install
147
+ You can now install SeaVision using pip on both Linux and Windows run:
116
148
 
117
149
  ```bash
118
- pip install ".[<extras>]"
150
+ python -m pip install "seavision-python[<extras>]"
119
151
  ```
120
152
 
121
153
  SeaVision can be installed in various modes, each of which supports different modes of functionality. See below for a full
@@ -127,29 +159,19 @@ Use the install command that matches your use case.
127
159
 
128
160
  | User type | Install command | Primary CLI command(s) |
129
161
  |---|---|---|
130
- | Detection-only users (local videos) | `python -m pip install .` | `seavision` |
131
- | Detection users with videos in S3 bucket | `python -m pip install ".[s3]"` | `seavision` |
132
- | GUI users (includes S3 support) | `python -m pip install ".[gui]"` | `seavision-gui` |
133
- | Edge device operators (runtime only) | `python -m pip install ".[edge]"` | `seavision-edge` |
134
- | Export users (prepare edge artifacts) | `python -m pip install ".[export]"` | `seavision-export` |
135
- | Advanced/full users | `python -m pip install ".[all]"` | `seavision`, `seavision-gui`, `seavision-export`, `seavision-edge` |
136
-
137
- Most users should use either `python -m pip install ".[gui]"` for desktop-only usage or `python -m pip install ".[all]"` if they are
138
- also likely to use edge deployment functionality. Other installation methods may provide lighter dependencies in specific scenarios.
139
-
140
- You can verify your installation by running [test commands](#install-verification)
141
-
142
- ### Development install
143
-
144
- ```bash
145
- python -m venv venv
146
- venv\Scripts\activate.bat
147
- python -m pip install -e ".[dev]"
148
- ```
149
-
150
- For release/distribution policy and compatibility targets, see:
151
-
152
- - [Distribution and compatibility policy](./docs/release/Distribution_and_Compatibility.md)
162
+ | Detection-only users (local videos) | `python -m pip install seavision-python` | `seavision` |
163
+ | Detection users with videos in S3 bucket | `python -m pip install "seavision-python[s3]"` | `seavision` |
164
+ | GUI users (includes S3 support) | `python -m pip install "seavision-python[gui]"` | `seavision-gui` |
165
+ | Edge device operators (runtime only) | `python -m pip install "seavision-python[edge]"` | `seavision-edge` |
166
+ | Export users (prepare edge artifacts) | `python -m pip install "seavision-python[export]"` | `seavision-export` |
167
+ | Advanced/full users | `python -m pip install "seavision-python[all]"` | `seavision`, `seavision-gui`, `seavision-export`, `seavision-edge` |
168
+
169
+ Most users should use either `python -m pip install ".[gui]"` for desktop-only
170
+ usage or `python -m pip install ".[all]"` if they are also likely to use edge
171
+ deployment functionality. Other installation methods may provide lighter
172
+ dependencies in specific scenarios. For example, a user only wanting to use the
173
+ detection pipeline on a local machine may not need the S3 and GUI dependencies
174
+ and would therefore prefer the standard installation with no extras.
153
175
 
154
176
  ### Optional GPU acceleration
155
177
 
@@ -162,35 +184,18 @@ For example, to run on an NVIDIA RTX 5090 GPU with cuda 13 you could install
162
184
  the following:
163
185
 
164
186
  ```bash
165
- pip install torch>=2.9.0 torchvision>=0.20.0 --index-url https://download.pytorch.org/whl/cu130 --force-reinstall
187
+ python -m pip install torch>=2.9.0 torchvision>=0.20.0 --index-url https://download.pytorch.org/whl/cu130 --force-reinstall
166
188
  ```
189
+
167
190
  You can find more information on PyTorch compatibility
168
191
  [here](https://pytorch.org/get-started/locally/).
169
192
 
170
- ### AWS S3 Access (Optional)
193
+ ### S3 Bucket Access (Optional)
171
194
 
172
- The pipeline supports streaming video directly from AWS. In order to access this
195
+ The pipeline supports streaming video directly from S3 buckets. In order to access this
173
196
  feature you will need to configure an AWS SSO profile. For more information on
174
197
  how to do this and integrate AWS streaming into the SeaVision workflow, see the
175
- [AWS setup documentation](./docs/AWS_SETUP.md)
176
-
177
- ## Install verification
178
-
179
- Run the command that matches your installed mode:
180
-
181
- ```bash
182
- # Detection CLI
183
- seavision --help
184
-
185
- # GUI
186
- seavision-gui
187
-
188
- # Export CLI
189
- seavision-export --help
190
-
191
- # Edge CLI
192
- seavision-edge --help
193
- ```
198
+ [AWS setup documentation](./docs/AWS_SETUP.md) # TODO: Verify the AWS set up docs
194
199
 
195
200
  ## Quick start
196
201
 
@@ -207,14 +212,32 @@ seavision --input ./data/footage/ --output ./results/
207
212
  seavision --config config/default.yaml
208
213
  ```
209
214
 
215
+ After installing SeaVision you can create a local copy of the config file by
216
+ running the following in a terminal:
217
+
218
+ ```bash
219
+ seavision --write-default-config "path/to/write/config.yml"
220
+ ```
221
+
222
+ Each argument in the config file is explained within the file. Specific detector
223
+ class documentation can also be found within the source code and may provide
224
+ additional context.
225
+
210
226
  ### 2. Launch the GUI
211
227
 
228
+ You can launch the SeaVision GUI by running hte following in a terminal:
229
+
212
230
  ```bash
213
231
  seavision-gui
214
232
  ```
215
233
 
234
+ Here, you can view, validate and manually modify detections created by the
235
+ SeaVision detection pipeline. See the [docs](TODO: GUI docs) for more info
236
+
216
237
  ### 3. Export for edge deployment
217
238
 
239
+ TODO: Need to verify these commands and update them.
240
+
218
241
  ```bash
219
242
  seavision-export --weights models/fish.pt --output ./deployment --target onnx
220
243
  ```
@@ -225,60 +248,32 @@ seavision-export --weights models/fish.pt --output ./deployment --target onnx
225
248
  seavision-edge --artifact-dir ./deployment/artifact
226
249
  ```
227
250
 
228
- ## Troubleshooting quick checks
229
-
230
- | Problem | Likely cause | Quick check | Fix |
231
- |---|---|---|---|
232
- | `seavision: command not found` | Package not installed in active environment | `python -m pip show seavision` | Activate the right environment and reinstall using the install matrix |
233
- | `seavision-gui: command not found` | GUI extra not installed | `python -m pip show PySide6` | `python -m pip install ".[gui]"` |
234
- | `seavision-edge: command not found` | Edge extra not installed | `python -m pip show onnxruntime` | `python -m pip install ".[edge]"` |
235
- | Import error for `boto3` when using S3 | S3 dependency missing | `python -m pip show boto3` | `python -m pip install ".[s3]"` or `python -m pip install ".[gui]"` |
236
- | GUI starts but S3 login fails | AWS credentials/session not configured | `aws sts get-caller-identity` | Run `aws sso login --profile <profile-name>` and retry |
237
- | Edge run fails at startup validation | Artifact dir incomplete or invalid | `seavision-edge --artifact-dir <path>` output | Re-run `seavision-export` and copy the full artifact directory again |
238
-
239
- ## Configuration
240
-
241
- The SeaVision pipeline can be fully customised using YAML config files. For
242
- a documented example of a config file see the
243
- [default configuration](./config/default.yaml)
244
-
245
-
246
- ## Edge Deployment
247
-
248
- Users may wish to deploy models developed or refined using SeaVision to an edge
249
- device. Full support is provided for deploying trained model weight files
250
- (`*.pt`) on Raspberry Pi.
251
-
252
- Edge deployment creates SeaVision detection files directly on the Pi which may
253
- save compute time, power and data transfer requirements. Users can optionally
254
- export periodic validation clips alongside the detections. See below for
255
- detailed documentation:
256
-
257
- If you are new to the deployment workflow, use this order:
258
-
251
+ For full documentation of the edge deployment process see here:
259
252
  1. [Edge deployment overview](./docs/edge/README.md)
260
253
  2. [Concepts and Terms](./docs/edge/Concepts%20and%20Terms.md)
261
254
  3. [Prerequisites Checklist](./docs/edge/Prerequisites%20Checklist.md)
262
255
  4. [Operator Quickstart](./docs/edge/Operator%20Quickstart.md)
263
256
  5. [Troubleshooting](./docs/edge/Troubleshooting.md)
264
257
 
265
- Use the technical references only when you are preparing the deployment files
266
- or troubleshooting the package structure:
258
+ ## Troubleshooting quick checks
259
+
260
+ | Problem | Likely cause | Quick check | Fix |
261
+ |---|---|---|---|
262
+ | `seavision: command not found` | Package not installed in active environment | `python -m pip show seavision` | Activate the right environment and reinstall |
263
+ | `seavision-gui: command not found` | GUI extra not installed | `python -m pip show PySide6` | `python -m pip install "seavision-python[gui]"` |
264
+ | `seavision-edge: command not found` | Edge extra not installed | `python -m pip show onnxruntime` | `python -m pip install "seavision-python[edge]"` |
265
+ | Import error for `boto3` when using S3 | S3 dependency missing | `python -m pip show boto3` | `python -m pip install ".[s3]"` or `python -m pip install "seavision-python[gui]"` |
266
+ | GUI starts but S3 login fails | AWS credentials/session not configured | `aws sts get-caller-identity` | Run `aws sso login --profile <profile-name>` and retry |
267
267
 
268
- - [Deploy to Raspberry Pi](./docs/edge/Deploy%20to%20Raspberry%20Pi.md)
269
- - [Troubleshooting](./docs/edge/Troubleshooting.md)
270
- - [Wheel runtime workflow](./docs/edge/Wheel%20Runtime.md)
271
- - [Model artifact layout](./docs/edge/Model%20Artifacts.md)
272
- - [Rollback runbook](./docs/edge/Rollback%20Runbook.md)
273
268
 
274
269
  ## Documentation
275
270
 
276
271
  - [Start Here guide](./docs/Start_Here.md)
277
- - [Class and API reference](./docs/Class_reference.md)
278
- - [Architecture and class diagrams](./docs/Class_diagram.md)
279
- - [AWS setup guide](./docs/AWS_SETUP.md)
272
+ - [Class and API reference](./docs/Class_reference.md) TODO: Reproduce class reference
273
+ - [Architecture and class diagrams](./docs/Class_diagram.md) # TODO: Reproduce class diagrams
274
+ - [AWS setup guide](./docs/AWS_SETUP.md) # TODO: Check this guide is up to date and user friendly
280
275
  - [Edge deployment docs](./docs/edge/README.md)
281
- - [GUI docs](./docs/gui/README.md)
276
+ - [GUI docs](./docs/gui/README.md) # ENsure the GUI docs are comprehensive and user firendly
282
277
 
283
278
  ## Project Status
284
279
 
@@ -0,0 +1,226 @@
1
+ <p align="left">
2
+ <img src="https://raw.githubusercontent.com/mariolambrette/SeaVision/Main/assets/seavision_logo.jpg" alt="Logo" width="200"/>
3
+ </p>
4
+
5
+ # SeaVision
6
+
7
+ ## Human-in-the-loop Computer Vision for Marine Environments
8
+
9
+ > [!WARNING]
10
+ > Documentation is currently out of date.
11
+ > The packaging, release, and edge-deployment flows have changed recently, and
12
+ > some instructions in this README and the linked docs may still describe older
13
+ > clone-first or pre-release workflows. Treat the published release artifacts
14
+ > and current CLI behavior as the source of truth until the docs are refreshed.
15
+
16
+ SeaVision offers a practical computer vision workflow for marine monitoring. It supports the development of accurate,
17
+ custom detection models for specific deployment scenarios. A typical SeaVision
18
+ workflow involves:
19
+
20
+ 1. Record marine monitoring footage
21
+ - This footage can be recorded to a hard drive, stored directly on a
22
+ workstation or stored in an [S3 bucket](https://en.wikipedia.org/wiki/Amazon_S3)
23
+ in the cloud.
24
+
25
+ 2. Process the footage with a generalisable detector.
26
+ - This first-pass processing uses a coarse, generalisable detector that
27
+ returns candiate detections for manual review.
28
+ - Currently implemented detectors include [SAM3](https://ai.meta.com/research/sam3/)-based semantic detection,
29
+ motion detection, and the [Community Fish Detector](https://github.com/filippovarini/community-fish-detector)
30
+
31
+ 3. Use the [SeaVision GUI](TODO: Link to GUI docs) to review the output of the
32
+ generalisable detector.
33
+ - The GUI is used for validation (i.e. how accurate is the generalisable
34
+ detector on my footage?) and for generating training data.
35
+
36
+ 4. Train a custom model using the GUI outputs
37
+ - Annotations made in the GUI can be exported and [converted to YOLO format](TODO: docs for converting SeaVision detections o YOLO format).
38
+ - These annotations can be used to train a custom YOLO detection model with
39
+ the ultralytics framework. See [here](https://docs.ultralytics.com/modes/train/) for details.
40
+ - Model training within SeaVision is not currently supported as the ultralytics
41
+ API abstracts most complexity already.
42
+
43
+ 5. Deploy the trained detection model on recorded and furture footage.
44
+ - The trained YOLO model can be deployed using the SeaVision frameowrk by using
45
+ the YOLODetector class.
46
+ - Users can deploy the model on a worstation, on the cloud or onto an edge
47
+ device.
48
+
49
+ If you are new to the project, start with the [Start Here guide](./docs/Start_Here.md).
50
+
51
+ ## Installation
52
+
53
+ ### Prerequisites
54
+
55
+ - Python 3.10-3.12
56
+ - pip
57
+ - SeaVision is currently only tested on Windows and Linux systems. Installations
58
+ on MacOS have not been thouroughly tested though may work in certain
59
+ circumstances
60
+
61
+ ### Install with pip
62
+
63
+ SeaVision can be installed using pip in a suitable python environemnt.
64
+
65
+ #### Conda
66
+ For conda users:
67
+ ```bash
68
+ conda create -n seavision python=3.11
69
+ conda activate seavision
70
+ python -m pip install --upgrade pip
71
+ ```
72
+
73
+ #### Venv (Windows)
74
+ For windows users without conda run the following in a powershell terminal:
75
+ ```bash
76
+ py -3.11 -m venv .venv-seavision
77
+ .\.venv-seavision\Scripts\Activate.ps1
78
+ python -m pip install --upgrade pip
79
+ ```
80
+
81
+ #### Venv (Linux)
82
+ In Linux, without conda, run the following:
83
+ ```bash
84
+ python3.11 -m venv .venv-seavision
85
+ source .venv-seavision/bin/activate1
86
+ python -m pip install --upgrade pip
87
+ ```
88
+
89
+ *NB: python versions 3.10 and 3.12 will also work*
90
+
91
+ #### Install
92
+ You can now install SeaVision using pip on both Linux and Windows run:
93
+
94
+ ```bash
95
+ python -m pip install "seavision-python[<extras>]"
96
+ ```
97
+
98
+ SeaVision can be installed in various modes, each of which supports different modes of functionality. See below for a full
99
+ description of all installation modes.
100
+
101
+ ### Install Matrix (User Types)
102
+
103
+ Use the install command that matches your use case.
104
+
105
+ | User type | Install command | Primary CLI command(s) |
106
+ |---|---|---|
107
+ | Detection-only users (local videos) | `python -m pip install seavision-python` | `seavision` |
108
+ | Detection users with videos in S3 bucket | `python -m pip install "seavision-python[s3]"` | `seavision` |
109
+ | GUI users (includes S3 support) | `python -m pip install "seavision-python[gui]"` | `seavision-gui` |
110
+ | Edge device operators (runtime only) | `python -m pip install "seavision-python[edge]"` | `seavision-edge` |
111
+ | Export users (prepare edge artifacts) | `python -m pip install "seavision-python[export]"` | `seavision-export` |
112
+ | Advanced/full users | `python -m pip install "seavision-python[all]"` | `seavision`, `seavision-gui`, `seavision-export`, `seavision-edge` |
113
+
114
+ Most users should use either `python -m pip install ".[gui]"` for desktop-only
115
+ usage or `python -m pip install ".[all]"` if they are also likely to use edge
116
+ deployment functionality. Other installation methods may provide lighter
117
+ dependencies in specific scenarios. For example, a user only wanting to use the
118
+ detection pipeline on a local machine may not need the S3 and GUI dependencies
119
+ and would therefore prefer the standard installation with no extras.
120
+
121
+ ### Optional GPU acceleration
122
+
123
+ The above install allows you to run all SeaVision functionality but does not
124
+ provide support for GPU-accelerated processing. Some methods (e.g. SAM3-based
125
+ detection) will be significantly faster if a GPU is available. You will need to
126
+ install GPU-specific dependencies manually based on your hardware.
127
+
128
+ For example, to run on an NVIDIA RTX 5090 GPU with cuda 13 you could install
129
+ the following:
130
+
131
+ ```bash
132
+ python -m pip install torch>=2.9.0 torchvision>=0.20.0 --index-url https://download.pytorch.org/whl/cu130 --force-reinstall
133
+ ```
134
+
135
+ You can find more information on PyTorch compatibility
136
+ [here](https://pytorch.org/get-started/locally/).
137
+
138
+ ### S3 Bucket Access (Optional)
139
+
140
+ The pipeline supports streaming video directly from S3 buckets. In order to access this
141
+ feature you will need to configure an AWS SSO profile. For more information on
142
+ how to do this and integrate AWS streaming into the SeaVision workflow, see the
143
+ [AWS setup documentation](./docs/AWS_SETUP.md) # TODO: Verify the AWS set up docs
144
+
145
+ ## Quick start
146
+
147
+ ### 1. Run the detection pipeline
148
+
149
+ The full detection pipeline can be run with a CLI command, which can optionally be configured
150
+ with a [YAML file](./config/default.yaml)
151
+
152
+ ```bash
153
+ # Local files
154
+ seavision --input ./data/footage/ --output ./results/
155
+
156
+ # With config file
157
+ seavision --config config/default.yaml
158
+ ```
159
+
160
+ After installing SeaVision you can create a local copy of the config file by
161
+ running the following in a terminal:
162
+
163
+ ```bash
164
+ seavision --write-default-config "path/to/write/config.yml"
165
+ ```
166
+
167
+ Each argument in the config file is explained within the file. Specific detector
168
+ class documentation can also be found within the source code and may provide
169
+ additional context.
170
+
171
+ ### 2. Launch the GUI
172
+
173
+ You can launch the SeaVision GUI by running hte following in a terminal:
174
+
175
+ ```bash
176
+ seavision-gui
177
+ ```
178
+
179
+ Here, you can view, validate and manually modify detections created by the
180
+ SeaVision detection pipeline. See the [docs](TODO: GUI docs) for more info
181
+
182
+ ### 3. Export for edge deployment
183
+
184
+ TODO: Need to verify these commands and update them.
185
+
186
+ ```bash
187
+ seavision-export --weights models/fish.pt --output ./deployment --target onnx
188
+ ```
189
+
190
+ ### 4. Run on an edge device
191
+
192
+ ```bash
193
+ seavision-edge --artifact-dir ./deployment/artifact
194
+ ```
195
+
196
+ For full documentation of the edge deployment process see here:
197
+ 1. [Edge deployment overview](./docs/edge/README.md)
198
+ 2. [Concepts and Terms](./docs/edge/Concepts%20and%20Terms.md)
199
+ 3. [Prerequisites Checklist](./docs/edge/Prerequisites%20Checklist.md)
200
+ 4. [Operator Quickstart](./docs/edge/Operator%20Quickstart.md)
201
+ 5. [Troubleshooting](./docs/edge/Troubleshooting.md)
202
+
203
+ ## Troubleshooting quick checks
204
+
205
+ | Problem | Likely cause | Quick check | Fix |
206
+ |---|---|---|---|
207
+ | `seavision: command not found` | Package not installed in active environment | `python -m pip show seavision` | Activate the right environment and reinstall |
208
+ | `seavision-gui: command not found` | GUI extra not installed | `python -m pip show PySide6` | `python -m pip install "seavision-python[gui]"` |
209
+ | `seavision-edge: command not found` | Edge extra not installed | `python -m pip show onnxruntime` | `python -m pip install "seavision-python[edge]"` |
210
+ | Import error for `boto3` when using S3 | S3 dependency missing | `python -m pip show boto3` | `python -m pip install ".[s3]"` or `python -m pip install "seavision-python[gui]"` |
211
+ | GUI starts but S3 login fails | AWS credentials/session not configured | `aws sts get-caller-identity` | Run `aws sso login --profile <profile-name>` and retry |
212
+
213
+
214
+ ## Documentation
215
+
216
+ - [Start Here guide](./docs/Start_Here.md)
217
+ - [Class and API reference](./docs/Class_reference.md) TODO: Reproduce class reference
218
+ - [Architecture and class diagrams](./docs/Class_diagram.md) # TODO: Reproduce class diagrams
219
+ - [AWS setup guide](./docs/AWS_SETUP.md) # TODO: Check this guide is up to date and user friendly
220
+ - [Edge deployment docs](./docs/edge/README.md)
221
+ - [GUI docs](./docs/gui/README.md) # ENsure the GUI docs are comprehensive and user firendly
222
+
223
+ ## Project Status
224
+
225
+ Note that this project is under active development and features may not yet
226
+ work as intended.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "seavision-python"
7
- version = "0.1.1"
7
+ version = "0.1.2"
8
8
  description = "Human-in-the-loop Computer Vision for Marine Environments"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -1,3 +1,3 @@
1
1
  """SeaVision - Human-in-the-loop Computer Vision for Marine Environments."""
2
2
 
3
- __version__ = "0.1.1"
3
+ __version__ = "0.1.2"
@@ -6,6 +6,7 @@ from typing import List, Optional
6
6
 
7
7
  from .base import VideoSource
8
8
  from .local import LocalVideoSource
9
+ from .s3 import S3VideoSource
9
10
 
10
11
  logger = logging.getLogger(__name__)
11
12
 
@@ -13,7 +14,7 @@ logger = logging.getLogger(__name__)
13
14
  def discover_local_videos(
14
15
  path: str,
15
16
  pattern: str = "*.ts"
16
- ) -> List[VideoSource]:
17
+ ) -> List[LocalVideoSource]:
17
18
  """
18
19
  Discover video files on the local file system.
19
20
 
@@ -64,7 +65,7 @@ def discover_s3_videos(
64
65
  region_name: Optional[str] = None,
65
66
  profile_name: Optional[str] = None,
66
67
  endpoint_url: Optional[str] = None,
67
- ) -> List[VideoSource]:
68
+ ) -> List[S3VideoSource]:
68
69
  """
69
70
  Discover video files in an S3 bucket.
70
71
 
@@ -107,7 +108,6 @@ def discover_s3_videos(
107
108
  )
108
109
 
109
110
  from fnmatch import fnmatch
110
- from .s3 import S3VideoSource
111
111
 
112
112
  # Create S3 client via session (supports SSO profiles and custom endpoints)
113
113
  session = boto3.Session(