Skip to content

Commit 139341a

Browse files
osyounisosyounis
authored
Merge pull request #1 from osyounis/dev
Release v0.1.0 - Collision Avoidance Radar Plotter
2 parents e6ee85a + 4c1bbe2 commit 139341a

33 files changed

+3318
-12
lines changed

‎.github/workflows/lint.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Lint
2+
3+
on:
4+
push:
5+
branches: [ main, dev ]
6+
pull_request:
7+
branches: [ main, dev ]
8+
9+
jobs:
10+
lint:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- name: Install uv
17+
uses: astral-sh/setup-uv@v6
18+
with:
19+
version: "latest"
20+
21+
- name: Set up Python
22+
run: uv python install 3.12
23+
24+
- name: Install dependencies
25+
run: |
26+
uv sync
27+
uv pip install -e .
28+
29+
- name: Run ruff check
30+
run: uv run ruff check .
31+
32+
- name: Run ruff format check
33+
run: uv run ruff format --check .
34+
35+
- name: Run mypy
36+
run: uv run mypy src/

‎.github/workflows/tests.yml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: Tests
2+
3+
on:
4+
push:
5+
branches: [ main, dev ]
6+
pull_request:
7+
branches: [ main, dev ]
8+
9+
jobs:
10+
tests:
11+
runs-on: ${{ matrix.os }}
12+
strategy:
13+
matrix:
14+
os: [ubuntu-latest]
15+
python-version: ['3.12']
16+
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- name: Install uv
21+
uses: astral-sh/setup-uv@v6
22+
with:
23+
version: "latest"
24+
25+
- name: Set up Python ${{ matrix.python-version }}
26+
run: uv python install ${{ matrix.python-version }}
27+
28+
- name: Install dependencies
29+
run: |
30+
uv sync
31+
uv pip install -e .
32+
33+
- name: Run tests with pytest
34+
run: |
35+
uv run pytest --cov=src/radar_plotter --cov-report=xml --cov-report=term-missing
36+
37+
- name: Upload coverage to Codecov
38+
uses: codecov/codecov-action@v5
39+
with:
40+
files: ./coverage.xml
41+
fail_ci_if_error: false
42+
token: ${{ secrets.CODECOV_TOKEN }}
43+
44+
- name: Run type checking
45+
run: |
46+
uv run mypy src/
47+
48+
- name: Run linting
49+
run: |
50+
uv run ruff check .
51+

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,3 +231,6 @@ ehthumbs_vista.db
231231
*.stackdump
232232
[Dd]esktop.ini
233233
$RECYCLE.BIN/
234+
235+
# Other Files
236+
CLAUDE.md

‎README.md‎

Lines changed: 178 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,193 @@
1-
# Collision Avoidance Radar Plotting App
1+
# ⚓ Collision Avoidance Radar Plotting App
22

3-
A Python application to calculate a collision avoidance radar plot to help others train this skill.
3+
A Python application for calculating collision avoidance radar plots to help maritime navigators train and practice this essential skill.
44

55
[![Tests](https://github.com/osyounis/collision_avoidance_radar_plotting_app/actions/workflows/tests.yml/badge.svg)](https://github.com/osyounis/collision_avoidance_radar_plotting_app/actions/workflows/tests.yml)
6-
![Static Badge](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)
7-
![GitHub License](https://img.shields.io/github/license/osyounis/islamic_prayer_time_app)
6+
[![codecov](https://codecov.io/gh/osyounis/collision_avoidance_radar_plotting_app/graph/badge.svg)](https://codecov.io/gh/osyounis/collision_avoidance_radar_plotting_app)
7+
![Python](https://img.shields.io/badge/python-3.12-blue?logo=python&logoColor=white)
8+
![License](https://img.shields.io/github/license/osyounis/collision_avoidance_radar_plotting_app)
9+
10+
---
11+
12+
## 📋 Features
13+
14+
- **Calculate CPA** (Closest Point of Approach)
15+
- **Determine maneuvers** for collision avoidance
16+
- **Visualize radar plots** with interactive graphics and vector arrows
17+
- **Web interface** for non-technical users (Streamlit)
18+
- **Python API** for advanced users
19+
- **Educational tool** for Coast Guard Auxiliary and maritime training
20+
21+
---
22+
23+
## 🚀 Quick Start
24+
25+
### Installation
26+
27+
```bash
28+
# Clone the repository
29+
git clone https://github.com/osyounis/collision_avoidance_radar_plotting_app.git
30+
cd collision_avoidance_radar_plotting_app
31+
32+
# Install with uv (recommended)
33+
uv sync
34+
35+
# Or with pip
36+
pip install -e .
37+
```
38+
39+
### Running the Web App
40+
41+
```bash
42+
# With uv
43+
uv run streamlit run app.py
44+
45+
# Or directly
46+
streamlit run app.py
47+
```
48+
49+
Then open your browser to `http://localhost:8501`
50+
51+
---
52+
53+
## 📖 Usage
54+
55+
### Web Interface (Recommended for most users)
56+
57+
1. Run the Streamlit app (see above)
58+
2. Enter your vessel's course and speed
59+
3. Set maneuver parameters (Maneuver Distance and Keep Out Distance)
60+
4. Enter contact vessel observations (Point R and Point M)
61+
5. Click "Calculate Solution"
62+
63+
### Python API
64+
65+
```python
66+
from radar_plotter.models import RadarProblem, RadarPoint
67+
from radar_plotter.solver import solver_radar_problem
68+
69+
# Define the problem
70+
problem = RadarProblem(
71+
our_course=0.0,
72+
our_speed=10.0,
73+
maneuver_dist=5.0,
74+
new_cpa_dist=2.5,
75+
r_point=RadarPoint(45.0, 11.5, "14:00"),
76+
m_point=RadarPoint(43.0, 9.0, "14:06")
77+
)
78+
79+
# Solve
80+
solution = solver_radar_problem(problem)
81+
82+
print(f"CPA: {solution.cpa_range:.1f} NM at {solution.cpa_time:%H:%M}")
83+
print(f"New Course: {solution.new_course:.0f}°")
84+
print(f"New Speed: {solution.new_speed:.0f} kts")
85+
```
86+
87+
### Command Line Examples
88+
89+
```bash
90+
# Run a basic calculation
91+
uv run python examples/basic_calculation.py
92+
93+
# Display an animated radar plot
94+
uv run python examples/animated_plot.py
95+
```
96+
97+
---
98+
99+
## 🧪 Development
100+
101+
### Running Tests
102+
103+
```bash
104+
uv run pytest # Run all tests
105+
uv run pytest -v # Verbose output
106+
uv run pytest --cov=radar_plotter # With coverage
107+
uv run pytest --cov=radar_plotter --cov-report=html # Coverage + HTML report
108+
```
109+
110+
### Linting and Type Checking
111+
112+
```bash
113+
uv run ruff check . # Linting
114+
uv run ruff format . # Auto-format
115+
uv run mypy src/ # Type checking
116+
```
117+
118+
### Project Structure
119+
120+
```
121+
src/radar_plotter/
122+
├── core/ # Core calculation modules
123+
│ ├── coordinates.py # Polar ↔ Cartesian conversion
124+
│ ├── cpa.py # Closest Point of Approach
125+
│ ├── maneuvers.py # Collision avoidance maneuvers
126+
│ ├── relative_motion.py # SRM/DRM calculations
127+
│ └── true_motion.py # STM/DTM calculations
128+
├── plotting/ # Visualization
129+
│ ├── animation.py # Animated radar plots
130+
│ └── radar_plot.py # Static radar plots
131+
├── models.py # Data models (RadarProblem, RadarSolution)
132+
├── solver.py # Main solver orchestration
133+
└── scenarios.py # Pre-defined test scenarios
134+
```
135+
136+
---
137+
138+
## 📚 Theory
139+
140+
Collision Avoidance Radar Plotting is a maritime navigation technique used to:
141+
- Track vessel movements on radar
142+
- Calculate closest point of approach (CPA)
143+
- Determine required maneuvers to avoid collisions
144+
- Comply with COLREGs (International Regulations for Preventing Collisions at Sea)
145+
146+
### Key Concepts:
147+
148+
- **CPA**: Closest Point of Approach - minimum distance to target
149+
- **SRM**: Speed of Relative Movement
150+
- **DRM**: Direction of Relative Movement
151+
- **STM**: Speed of True Movement
152+
- **DTM**: Direction of True Movement
153+
- **N/C**: New Course required to avoid collision
154+
- **N/S**: New Speed required to avoid collision
155+
156+
---
157+
158+
## 🤝 Contributing
159+
160+
Contributions are welcome! Please:
161+
1. Fork the repository
162+
2. Create a feature branch from `dev`
163+
3. Make your changes
164+
4. Run tests and linting: `uv run pytest && uv run ruff check .`
165+
5. Submit a pull request to `dev`
8166

9167
---
10168

11169
## 🪪 License
170+
12171
This project is licensed under **GNU General Public License v3.0 or later (GPL-3.0-or-later).**
13172

14-
See [LICENSE](https://github.com/osyounis/collision_avoidance_radar_plotting_app/blob/main/LICENSE) for full text.
173+
See [LICENSE](LICENSE) for full text.
174+
175+
---
176+
177+
## ⚠️ Disclaimer
178+
179+
**This is an educational tool ONLY.** It should NOT be used for real collision avoidance situations. Always follow proper maritime navigation procedures and COLREGs.
15180

16181
---
17182

18183
## ✍️ Author
184+
19185
**Omar Younis**
20186

21-
---
187+
---
188+
189+
## 🙏 Acknowledgments
190+
191+
- U.S. Coast Guard Auxiliary for radar plotting training materials
192+
- Northeast Maritime Institute for [instructional videos](https://www.youtube.com/@nmi-edu)
193+
- Developed with modern Python best practices using `uv` and Streamlit

0 commit comments

Comments
 (0)