# Sea Voyage
seavoyage는 해상 네트워크 기반의 선박 경로 탐색, 커스텀 제한구역(해역) 적용, 네트워크 시각화 등 다양한 해양 경로 분석 기능을 제공하는 Python 패키지입니다. 이 패키지는 [searoute](https://github.com/genthalili/searoute-py) 패키지를 기반으로 개선되었습니다.
## 원본 프로젝트
- 원본 패키지: [searoute](https://github.com/genthalili/searoute-py)
- 원작자: Gent Halili
- 라이선스: Apache License 2.0
## 주요 기능
- 해상 네트워크 기반 최적 경로 탐색
- 커스텀 제한구역(GeoJSON) 등록 및 적용
- 다양한 해상 네트워크 해상도(5km~100km) 지원
- folium 기반 경로/네트워크 지도 시각화
- 네트워크 및 경로의 GeoJSON 변환
## 설치
```bash
pip install seavoyage
```
## 개발 모드 설치
개발 중에 테스트를 쉽게 실행하려면 다음 명령으로 패키지를 개발 모드로 설치하세요:
```bash
pip install -e .
```
이렇게 하면 `pytest.ps1` 스크립트를 사용하지 않고도 바로 `pytest` 명령을 실행할 수 있습니다.
## 빠른 시작
### 1. 기본 경로 생성
```python
import seavoyage as sv
# 출발지와 도착지 좌표 (경도, 위도)
start = (129.17, 35.075)
end = (-4.158, 44.644)
# 기본 해상 네트워크에서 최적 경로 탐색
route = sv.seavoyage(start, end)
print("경로 길이:", route["properties"]["length"], "km")
print("예상 소요 시간:", route["properties"]["duration_hours"], "시간")
```
### 2. 커스텀 제한구역(해역) 적용
```python
# 제한구역 GeoJSON 파일 등록 (예: 'jwc.geojson')
sv.register_custom_restriction('jwc', '/path/to/jwc.geojson')
# 제한구역을 적용하여 경로 탐색
route = sv.seavoyage(start, end, restrictions=['jwc'])
print("제한구역 적용 후 경로 길이:", route["properties"]["length"], "km")
```
### 3. 다양한 해상 네트워크 해상도 사용
#### 3.1 미리 설정된 해상 네트워크 사용
```python
# 5km, 10km, 20km, 50km, 100km 네트워크 지원
mnet_5km = sv.get_m_network_5km()
route = sv.seavoyage(start, end, M=mnet_5km)
```
#### 3.2 사용자 정의 해상 네트워크 사용
```python
# 사용자 정의 해상 네트워크 생성
mnet = sv.MNetwork().from_geojson('/path/to/mnet.geojson')
route = sv.seavoyage(start, end, M=mnet)
```
### 4. folium 기반 지도 시각화
```python
from seavoyage.utils import map_folium
# folium 지도 객체로 변환
m = map_folium(route)
m.save("route_map.html")
```
## 주요 API
- `seavoyage(start, end, restrictions=None, M=None, ...)`
: 최적 경로 탐색 (제한구역, 네트워크 해상도 등 옵션 지원)
- `MNetwork`
: 해상 네트워크 객체 (노드/엣지 추가, GeoJSON 변환 등 지원)
- `register_custom_restriction(name, geojson_file_path)`
: 커스텀 제한구역 등록
- `list_custom_restrictions()`
: 등록된 제한구역 이름 목록 반환
- `get_custom_restriction(name)`
: 제한구역 객체 반환
- `map_folium(data, ...)`
: folium 기반 지도 시각화
## 라이선스
이 프로젝트는 Apache License 2.0 라이선스 하에 배포됩니다.
```
Copyright 2024 - Gent Halili (원작자)
Copyright 2025 - Byeonggong Hwang
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```
## 기여
버그 리포트, 기능 제안, 풀 리퀘스트는 언제나 환영합니다.
## 연락처
- 이메일: bk22106@gmail.com
- GitHub: [a22106](https://github.com/a22106)
Raw data
{
"_id": null,
"home_page": "https://github.com/a22106/seavoyage",
"name": "seavoyage",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "sea route, shortest path, graph, geojson, networkx",
"author": "Byeonggong Hwang",
"author_email": "bk22106@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/25/a4/b49ca8a595f973ad1068e7fa39be6c55992f2688fb76621e109bee4786d1/seavoyage-0.1.9.tar.gz",
"platform": null,
"description": "# Sea Voyage\r\n\r\nseavoyage\ub294 \ud574\uc0c1 \ub124\ud2b8\uc6cc\ud06c \uae30\ubc18\uc758 \uc120\ubc15 \uacbd\ub85c \ud0d0\uc0c9, \ucee4\uc2a4\ud140 \uc81c\ud55c\uad6c\uc5ed(\ud574\uc5ed) \uc801\uc6a9, \ub124\ud2b8\uc6cc\ud06c \uc2dc\uac01\ud654 \ub4f1 \ub2e4\uc591\ud55c \ud574\uc591 \uacbd\ub85c \ubd84\uc11d \uae30\ub2a5\uc744 \uc81c\uacf5\ud558\ub294 Python \ud328\ud0a4\uc9c0\uc785\ub2c8\ub2e4. \uc774 \ud328\ud0a4\uc9c0\ub294 [searoute](https://github.com/genthalili/searoute-py) \ud328\ud0a4\uc9c0\ub97c \uae30\ubc18\uc73c\ub85c \uac1c\uc120\ub418\uc5c8\uc2b5\ub2c8\ub2e4.\r\n\r\n## \uc6d0\ubcf8 \ud504\ub85c\uc81d\ud2b8\r\n- \uc6d0\ubcf8 \ud328\ud0a4\uc9c0: [searoute](https://github.com/genthalili/searoute-py)\r\n- \uc6d0\uc791\uc790: Gent Halili\r\n- \ub77c\uc774\uc120\uc2a4: Apache License 2.0\r\n\r\n## \uc8fc\uc694 \uae30\ub2a5\r\n- \ud574\uc0c1 \ub124\ud2b8\uc6cc\ud06c \uae30\ubc18 \ucd5c\uc801 \uacbd\ub85c \ud0d0\uc0c9\r\n- \ucee4\uc2a4\ud140 \uc81c\ud55c\uad6c\uc5ed(GeoJSON) \ub4f1\ub85d \ubc0f \uc801\uc6a9\r\n- \ub2e4\uc591\ud55c \ud574\uc0c1 \ub124\ud2b8\uc6cc\ud06c \ud574\uc0c1\ub3c4(5km~100km) \uc9c0\uc6d0\r\n- folium \uae30\ubc18 \uacbd\ub85c/\ub124\ud2b8\uc6cc\ud06c \uc9c0\ub3c4 \uc2dc\uac01\ud654\r\n- \ub124\ud2b8\uc6cc\ud06c \ubc0f \uacbd\ub85c\uc758 GeoJSON \ubcc0\ud658\r\n\r\n## \uc124\uce58\r\n```bash\r\npip install seavoyage\r\n```\r\n\r\n## \uac1c\ubc1c \ubaa8\ub4dc \uc124\uce58\r\n\uac1c\ubc1c \uc911\uc5d0 \ud14c\uc2a4\ud2b8\ub97c \uc27d\uac8c \uc2e4\ud589\ud558\ub824\uba74 \ub2e4\uc74c \uba85\ub839\uc73c\ub85c \ud328\ud0a4\uc9c0\ub97c \uac1c\ubc1c \ubaa8\ub4dc\ub85c \uc124\uce58\ud558\uc138\uc694:\r\n\r\n```bash\r\npip install -e .\r\n```\r\n\r\n\uc774\ub807\uac8c \ud558\uba74 `pytest.ps1` \uc2a4\ud06c\ub9bd\ud2b8\ub97c \uc0ac\uc6a9\ud558\uc9c0 \uc54a\uace0\ub3c4 \ubc14\ub85c `pytest` \uba85\ub839\uc744 \uc2e4\ud589\ud560 \uc218 \uc788\uc2b5\ub2c8\ub2e4.\r\n\r\n## \ube60\ub978 \uc2dc\uc791\r\n\r\n### 1. \uae30\ubcf8 \uacbd\ub85c \uc0dd\uc131\r\n```python\r\nimport seavoyage as sv\r\n\r\n# \ucd9c\ubc1c\uc9c0\uc640 \ub3c4\ucc29\uc9c0 \uc88c\ud45c (\uacbd\ub3c4, \uc704\ub3c4)\r\nstart = (129.17, 35.075)\r\nend = (-4.158, 44.644)\r\n\r\n# \uae30\ubcf8 \ud574\uc0c1 \ub124\ud2b8\uc6cc\ud06c\uc5d0\uc11c \ucd5c\uc801 \uacbd\ub85c \ud0d0\uc0c9\r\nroute = sv.seavoyage(start, end)\r\nprint(\"\uacbd\ub85c \uae38\uc774:\", route[\"properties\"][\"length\"], \"km\")\r\nprint(\"\uc608\uc0c1 \uc18c\uc694 \uc2dc\uac04:\", route[\"properties\"][\"duration_hours\"], \"\uc2dc\uac04\")\r\n```\r\n\r\n### 2. \ucee4\uc2a4\ud140 \uc81c\ud55c\uad6c\uc5ed(\ud574\uc5ed) \uc801\uc6a9\r\n```python\r\n# \uc81c\ud55c\uad6c\uc5ed GeoJSON \ud30c\uc77c \ub4f1\ub85d (\uc608: 'jwc.geojson')\r\nsv.register_custom_restriction('jwc', '/path/to/jwc.geojson')\r\n\r\n# \uc81c\ud55c\uad6c\uc5ed\uc744 \uc801\uc6a9\ud558\uc5ec \uacbd\ub85c \ud0d0\uc0c9\r\nroute = sv.seavoyage(start, end, restrictions=['jwc'])\r\nprint(\"\uc81c\ud55c\uad6c\uc5ed \uc801\uc6a9 \ud6c4 \uacbd\ub85c \uae38\uc774:\", route[\"properties\"][\"length\"], \"km\")\r\n```\r\n\r\n### 3. \ub2e4\uc591\ud55c \ud574\uc0c1 \ub124\ud2b8\uc6cc\ud06c \ud574\uc0c1\ub3c4 \uc0ac\uc6a9\r\n#### 3.1 \ubbf8\ub9ac \uc124\uc815\ub41c \ud574\uc0c1 \ub124\ud2b8\uc6cc\ud06c \uc0ac\uc6a9\r\n```python\r\n# 5km, 10km, 20km, 50km, 100km \ub124\ud2b8\uc6cc\ud06c \uc9c0\uc6d0\r\nmnet_5km = sv.get_m_network_5km()\r\nroute = sv.seavoyage(start, end, M=mnet_5km)\r\n```\r\n\r\n#### 3.2 \uc0ac\uc6a9\uc790 \uc815\uc758 \ud574\uc0c1 \ub124\ud2b8\uc6cc\ud06c \uc0ac\uc6a9\r\n```python\r\n# \uc0ac\uc6a9\uc790 \uc815\uc758 \ud574\uc0c1 \ub124\ud2b8\uc6cc\ud06c \uc0dd\uc131\r\nmnet = sv.MNetwork().from_geojson('/path/to/mnet.geojson')\r\nroute = sv.seavoyage(start, end, M=mnet)\r\n```\r\n\r\n### 4. folium \uae30\ubc18 \uc9c0\ub3c4 \uc2dc\uac01\ud654\r\n```python\r\nfrom seavoyage.utils import map_folium\r\n\r\n# folium \uc9c0\ub3c4 \uac1d\uccb4\ub85c \ubcc0\ud658\r\nm = map_folium(route)\r\nm.save(\"route_map.html\")\r\n```\r\n\r\n## \uc8fc\uc694 API\r\n- `seavoyage(start, end, restrictions=None, M=None, ...)`\r\n: \ucd5c\uc801 \uacbd\ub85c \ud0d0\uc0c9 (\uc81c\ud55c\uad6c\uc5ed, \ub124\ud2b8\uc6cc\ud06c \ud574\uc0c1\ub3c4 \ub4f1 \uc635\uc158 \uc9c0\uc6d0)\r\n- `MNetwork`\r\n: \ud574\uc0c1 \ub124\ud2b8\uc6cc\ud06c \uac1d\uccb4 (\ub178\ub4dc/\uc5e3\uc9c0 \ucd94\uac00, GeoJSON \ubcc0\ud658 \ub4f1 \uc9c0\uc6d0)\r\n- `register_custom_restriction(name, geojson_file_path)`\r\n: \ucee4\uc2a4\ud140 \uc81c\ud55c\uad6c\uc5ed \ub4f1\ub85d\r\n- `list_custom_restrictions()`\r\n: \ub4f1\ub85d\ub41c \uc81c\ud55c\uad6c\uc5ed \uc774\ub984 \ubaa9\ub85d \ubc18\ud658\r\n- `get_custom_restriction(name)`\r\n: \uc81c\ud55c\uad6c\uc5ed \uac1d\uccb4 \ubc18\ud658\r\n- `map_folium(data, ...)`\r\n: folium \uae30\ubc18 \uc9c0\ub3c4 \uc2dc\uac01\ud654\r\n\r\n## \ub77c\uc774\uc120\uc2a4\r\n\uc774 \ud504\ub85c\uc81d\ud2b8\ub294 Apache License 2.0 \ub77c\uc774\uc120\uc2a4 \ud558\uc5d0 \ubc30\ud3ec\ub429\ub2c8\ub2e4.\r\n\r\n```\r\nCopyright 2024 - Gent Halili (\uc6d0\uc791\uc790)\r\nCopyright 2025 - Byeonggong Hwang\r\n\r\nLicensed under the Apache License, Version 2.0 (the \"License\");\r\nyou may not use this file except in compliance with the License.\r\nYou may obtain a copy of the License at\r\n\r\n http://www.apache.org/licenses/LICENSE-2.0\r\n\r\nUnless required by applicable law or agreed to in writing, software\r\ndistributed under the License is distributed on an \"AS IS\" BASIS,\r\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r\nSee the License for the specific language governing permissions and\r\nlimitations under the License.\r\n```\r\n\r\n## \uae30\uc5ec\r\n\ubc84\uadf8 \ub9ac\ud3ec\ud2b8, \uae30\ub2a5 \uc81c\uc548, \ud480 \ub9ac\ud018\uc2a4\ud2b8\ub294 \uc5b8\uc81c\ub098 \ud658\uc601\ud569\ub2c8\ub2e4.\r\n\r\n## \uc5f0\ub77d\ucc98\r\n- \uc774\uba54\uc77c: bk22106@gmail.com\r\n- GitHub: [a22106](https://github.com/a22106)\r\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "An improved version of searoute package for calculating the shortest sea route between two points on Earth.",
"version": "0.1.9",
"project_urls": {
"Homepage": "https://github.com/a22106/seavoyage"
},
"split_keywords": [
"sea route",
" shortest path",
" graph",
" geojson",
" networkx"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8fed3fea47cfeef384a90d371154c18114e728c4aace9e4d5c99378b7eae11d9",
"md5": "640fbb3793e23357dc07fb79bc9450f8",
"sha256": "cb36fb0d61aa1e98931df79e10f2859fa0b9756bad8b51e0bf6351e632a86420"
},
"downloads": -1,
"filename": "seavoyage-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "640fbb3793e23357dc07fb79bc9450f8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 32749642,
"upload_time": "2025-04-21T07:58:08",
"upload_time_iso_8601": "2025-04-21T07:58:08.741538Z",
"url": "https://files.pythonhosted.org/packages/8f/ed/3fea47cfeef384a90d371154c18114e728c4aace9e4d5c99378b7eae11d9/seavoyage-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "25a4b49ca8a595f973ad1068e7fa39be6c55992f2688fb76621e109bee4786d1",
"md5": "54aafef49e30d0dbda415e9308983350",
"sha256": "ec26241fe102c1395467f2e2bde4bf836df32a857492fceefe8fb3cd61961f85"
},
"downloads": -1,
"filename": "seavoyage-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "54aafef49e30d0dbda415e9308983350",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 32338726,
"upload_time": "2025-04-21T07:58:16",
"upload_time_iso_8601": "2025-04-21T07:58:16.150910Z",
"url": "https://files.pythonhosted.org/packages/25/a4/b49ca8a595f973ad1068e7fa39be6c55992f2688fb76621e109bee4786d1/seavoyage-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-04-21 07:58:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "a22106",
"github_project": "seavoyage",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "geojson",
"specs": [
[
">=",
"3.2.0"
]
]
},
{
"name": "networkx",
"specs": [
[
">=",
"3.4.2"
]
]
},
{
"name": "searoute",
"specs": [
[
">=",
"1.4.3"
]
]
},
{
"name": "folium",
"specs": [
[
">=",
"0.19.5"
]
]
},
{
"name": "shapely",
"specs": [
[
">=",
"2.1.0"
]
]
},
{
"name": "geopandas",
"specs": [
[
">=",
"1.0.1"
]
]
},
{
"name": "fiona",
"specs": [
[
">=",
"1.10.1"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"1.6.1"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.15.2"
]
]
},
{
"name": "myst-parser",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "sphinx_rtd_theme",
"specs": [
[
">=",
"3.0.2"
]
]
}
],
"lcname": "seavoyage"
}
JSON
