세계 항로·해안 경로·항구 접근 경로를 생성합니다. 전역 그래프로 방문 순서를 정합니다. 수치 지형으로 수심을 검사하고, 육지 지도와 겹치는 경로를 제외합니다. WWW-POSIM은 이 계획기를 지형 작업자와 항해 관리기에 연결합니다.
Python 3.10 이상이 필요합니다. 지형 라이브러리와 함께 설치합니다.
git clone https://github.com/IOES-Lab/POSIM-Routing.git
cd POSIM-Routing
python -m venv .venv
. .venv/bin/activate
python -m pip install git+https://github.com/IOES-Lab/POSIM-Terrain.git@v0.1.0 -e .Windows에서는 .venv\Scripts\activate로 가상환경을 활성화합니다.
좌표는 WGS84의 [경도, 위도]입니다.
python -m posim_routing --start 129.08468 35.07446 --end 139.83 35.60 --output out/busan-tokyo.geojsonfrom posim_routing.global_route import route
course = route([129.08468, 35.07446], [139.83, 35.60])전역 항로는 searoute 1.4.3을 사용하며 기본값으로 파나마와 북서항로를 제외합니다. 다른 방문 경로에는 restrictions와 passage_gates를 지정합니다. 항구 목록 좌표와 수역의 도착 목표는 별도 입력입니다. 전역 항로만으로 수심을 확인할 수는 없습니다.
import numpy as np
from posim_routing.navigation import TerrainField, DetourPlanner
with np.load("out/busan/projected.npz") as grid:
field = TerrainField(grid["xs"], grid["ys"], grid["elevation"])
start = [0., 0., 0.]
goal = [100., 0., 0.]
planner = DetourPlanner(field, start, boat=True)
path = planner.route(start, goal)확인된 수역 안에서 출발점과 목표를 선택합니다. 자료가 없는 범위는 통과할 수 없습니다. 차량이 지나가는 전체 폭을 삼각형 충돌 지형과 비교합니다.
land.LandExcludedField(field, guard)로 수치 지형에 육지 검사를 추가합니다.
land.guard_from_spec(spec)는 캐시의 OSM 육지 자료를 읽습니다. 다른 로컬
압축 파일을 쓰려면 WWOS_COAST_OSM_ARCHIVE를 지정합니다. WWW-POSIM은 지형
자료 캐시에 이 파일을 준비합니다. 자료가 없으면 지역 경로 준비를 멈춥니다.
육지 자료로 경로를 제외할 수 있으며, 수심은 수치 지형으로 확인합니다.
지역 경로는 반도를 돌아가는 전체 지도 경로를 찾은 뒤 수심을 검사한 로컬 목표를 선택합니다. 우회 초반에는 항로 목표까지의 거리가 늘어날 수 있습니다. 검증된 구간의 끝에서는 다음 구간이 준비될 때까지 기다립니다. 날짜 변경선에서도 경도가 이어지도록 처리합니다.
목적지 항구로 진행할 때만 해안 가까운 경로를 우선합니다. 마지막 구간은 항로 목표와 항구를 향해야 합니다. 같은 후속 목표까지 검증한 짧은 경로보다 전체 거리가 100% 넘게 늘어나면 일반 수상 경로를 사용합니다. 육지나 여울을 피하려면 만과 섬을 돌아갈 수 있습니다. 항구와 필수 통과점은 도착 조건을 유지합니다.
후속 경유점은 검증된 구간의 끝을 표시합니다. 차량이 지나가는 전체 폭의 수심과 지도상 육지를 확인한 뒤 직선 구간의 중간 지점을 줄입니다. 육지와 수심 2 m 미만인 수역을 해안 경계로 보고 200 m를 띄웁니다. 이미 이 범위 안에 있는 차량은 선체 안전을 검사한 경로로 간격을 늘리며 빠져나옵니다. 네이티브 지형에서 실제 로컬 경로의 여유 거리를 다시 확인한 뒤 추진을 승인합니다.
해안에 합류한 뒤에는 육지에서 1.5 km 이내인 구간을 따릅니다. 서로 떨어진 해안 구간 사이에서는 전체 수상 연결 경로를 검사합니다. 해안 거리 한도는 다음 해안에 합류한 뒤 적용합니다. 먼바다 출구는 연결 검증에 사용하며, 별도 경로를 검사한 뒤 이동합니다. 일반 외해 항로의 굽이는 검증한 후속 해안 목표를 사용할 수 있으며, 실측 진행에 따라 항로 지점을 통과합니다. 항구와 필수 통과점은 순서대로 따릅니다. 일반 수상 경로를 선택하기 전에 진행 방향의 해안 접근 경로를 검사합니다. 해안 선호 경로를 갱신할 때는 후속 해안 구간이 준비될 때까지 기존의 검증된 구간을 유지합니다.
| 기준 | 기본값 |
|---|---|
| 수상 차량 로컬 수심 여유 | 1.5 m |
| 수상 차량 반경 + 추적 여유 | 3.5 m + 4 m |
| 해안 선호 거리 | 320 m |
| 지역 해안 추종 중 육지·얕은 수역과의 최대 거리 | 1.5 km |
| 해안 선호에 따른 추가 거리 한도 | 100% (전체 거리 2.0배) |
| 얕은 수역 제외 거리 / 경계 수심 | 200 m / 2 m |
| 도착 반경 | 300 m |
| 도착 목표 검사 | 반경 350 m / 수심 3 m |
arrival_targets.candidate(folder, port, radius=350., coast=None)는 생성한 지형에서 수상 도착 목표를 고릅니다. 선택적으로 connections.CoastConnector를 전달하면 OSM 육지 형상으로 검사 범위 전체를 확인합니다. 기본 검사 범위는 반경 300 m 도착 원과 바깥 여유 50 m를 포함합니다.
port_approach.corridor(tiles, spec, start, target)는 도착 영역으로 들어가는 가능한 경로를 비교합니다. connections.CoastConnector는 OSM 육지 형상으로 전역 항로와 항구 사이의 연결을 단축합니다. 이 검사는 해안선 여유만 확인하며 수심은 확인하지 않습니다.
도착 영역이 현재 적재된 지형 밖에 있으면 검증한 지역 접근 경로를 따라 이동합니다. 실제로 500 m 진행하면 전체 도착 경로를 다시 검사합니다. 수심이 없거나 도착 영역이 막혀 있으면 차량이 대기합니다.
항구를 지나쳐 돌아오는 경로를 줄이기 위해 앞쪽 외해 경유점도 연결 후보로 검사합니다. 필수 통과점과 보존하도록 지정한 경로 구간은 유지합니다. 탐색에 실패하면 입력 경로를 유지합니다. 실제 주행에는 수치 지형 검사가 필요합니다.
- 후보 경유점에서 항구까지의 거리: 1–500 km
- 해안 탐색 격자 한도: 1,000,000개
- 기본 격자 간격: 250 m
- 기본 육지 여유 거리: 80 m
- 기본 탐색 제한 시간: 10초
| 경로 | 내용 |
|---|---|
src/posim_routing/global_route.py |
해양 그래프와 필수 통과점 |
connections.py |
해안을 고려한 항구 연결 |
navigation.py, planning.py |
충돌 지형·차량 폭을 고려한 A*·지형 캐시 |
coastal.py |
해안 탐색과 수치 지형 경로 |
land.py, land_guidance.py |
육지 경로 제외와 범위를 제한한 우회 안내 |
regional.py |
비동기 지역 경로 준비 |
arrival_targets.py |
수치 지형과 선택적인 OSM 육지 검사로 도착 수역 선택 |
port_approach.py |
도착 영역 접근과 곡선 감속 |
course.py, navigation_frame.py |
항로 진행과 지리 좌표 전달 |
data/ |
Natural Earth 해안선과 출처 |
tests/ |
해안·자료 범위·백그라운드 계획 검사 |
RegionalNavigator는 /terrain/jobs와 지형 작업 조회를 위한 비동기 rpc(path, body=None, timeout=...) 함수를 받습니다. 선택적인 before_prepare 함수로 호출 앱의 캐시를 관리합니다. Gazebo 실행·종료는 호출 앱이 담당합니다.
같은 구간에서 일반 경유점을 통과할 때만 retain_coast=True를 사용합니다.
로컬 목표가 항로 경유점이면 최종 항구를 progress_target으로 전달합니다.
state['regional_waiting']이 있으면 검증된 다음 경로가 준비될 때까지 추진을
멈춥니다. 물리 계산과 센서 수신은 계속합니다. 갱신 경로는 검증된 기존 경로의
끝에서 시작하며, 남아 있는 전진 경유점을 유지합니다. 선택적인 해안 경로 준비에 실패하거나
결과가 비어 있어도 검증된 해안 경로를 외해 목표로 바꾸지 않습니다.
계획 감시는 제한 시간 안의 작업을 유지하고 완료된 결과부터 반영합니다.
경로 준비 지연만으로 차량의 물리적 후퇴를 요청하지 않습니다.
기본 지형 자료 서버에 연결할 수 없으면 더 작은 구역으로 경로를 계산합니다. 검증된 자료를 사용하며 수심과 육지 확인 기준은 같습니다.
- 해안에서 1.5 km 이내인 구역: 6 km × 6 km부터 검사
- 정밀 구역에서 안전한 연결 경로를 찾지 못하면: 20 km × 20 km로 확장
- 일반 지역 검사 범위: 20 km × 20 km
- 전체 백그라운드 경로 준비 제한 시간: 660초
- 자료 서버 장애 시 재시도 구역: 6 km × 6 km
- 두 구역 모두 자료 부족: 추진을 멈추고 재시도
python -m unittest discover -s tests코드: Apache-2.0. 출처 고지를 확인하세요. 경로는 시뮬레이션용이며 공인 항해 해도가 아닙니다.