Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 29 additions & 77 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,90 +1,42 @@
# POSIM — Platform for Ocean Simulation

POSIM is an open-source maritime robotics simulation library maintained by
IOES-Lab. It brings together ocean worlds, underwater vehicles, sensors, and
manipulation tasks for ROS 2 and Gazebo.

POSIM continues the [DAVE](https://github.com/IOES-Lab/dave) codebase, originally
developed as [Project DAVE](https://github.com/Field-Robotics-Lab/dave). This
repository preserves the source history, existing copyright notices, and
Apache-2.0 license.

## Current development version

The `main` branch targets **Ubuntu 26.04, ROS 2 Lyrical, and Gazebo Jetty**.
The initial POSIM import is based on DAVE `ros2` commit
[`8a3f6ab`](https://github.com/IOES-Lab/dave/commit/8a3f6abc2ba14ced787aff8befa0201f6c80ca8c).
POSIM 1.0 has not been released.

ROS packages, plugin namespaces and launch files use the `posim_` prefix.
Rebuild in a clean workspace when migrating from the earlier `dave_` names.
Existing third-party source attribution is retained.

## Get started

1. Run `extras/ros-lyrical-gz-jetty-install.sh`, or build `.docker/lyrical.amd64.dockerfile` / `.docker/lyrical.arm64v8.dockerfile` from this checkout.
2. Open a terminal with the installed ROS and workspace environments loaded.
3. Start a world:

```bash
ros2 launch posim_demos posim_world.launch.py world_name:=posim_ocean_waves
```

For a server-only run, append `headless:=true`. On a desktop with rendering
available, start REXROV with:

```bash
ros2 launch posim_demos posim_robot.launch.py \
namespace:=rexrov world_name:=posim_ocean_waves z:=-5 paused:=false
```

World and model references may download assets from Gazebo Fuel on first use.
More examples are in [the demo guide](examples/posim_demos/README.md).

## Library contents

- `models/`: world, vehicle, sensor, and object descriptions and their resources.
- `gazebo/`: model, sensor, world, ROS bridge, and multibeam sonar plugins.
- `examples/posim_demos/`: world, robot, sensor, and object launch entry points.
- `posim_interfaces/`: ROS messages and services used by the library.
- `extras/`: dependency installation, repository manifests, and development tools.
IOES-Lab. It combines ocean environments, underwater and surface robots,
simulated sensors, and ROS 2 control interfaces for Gazebo.

## Documentation

Read the [English guide](website/content/en/index.md) or
[한국어 가이드](website/content/ko/index.md) for installation, examples, custom
models and plugin references. The guides adapt the IOES-Lab Notion Wiki to
the current source layout.
**[English documentation](https://ioes-lab.github.io/POSIM/)** ·
**[한국어 문서](https://ioes-lab.github.io/POSIM/ko/)**

The [documentation website](website/README.md) uses the WWW-POSIM documentation
design and provides search, command copying and mobile navigation. It builds
to static HTML and can be deployed independently on Vercel or another static
host. Building it does not build or run Gazebo.
Find installation instructions, first simulations, vehicle and sensor examples,
custom robot guides, and plugin references on the documentation website.
The `main` branch targets Ubuntu 26.04, ROS 2 Lyrical, and Gazebo Jetty.
Start with [installation](https://ioes-lab.github.io/POSIM/install.html) or
[Docker](https://ioes-lab.github.io/POSIM/docker.html), then run your
[first simulation](https://ioes-lab.github.io/POSIM/quickstart.html).

## Contributing
## Try WWW-POSIM

Open issues and pull requests in [IOES-Lab/POSIM](https://github.com/IOES-Lab/POSIM).
Include the source revision, operating system, architecture, launch command,
and relevant logs when reporting a problem. Install and run the repository's
pre-commit hooks before submitting changes:
[WWW-POSIM — World Wide Web Platform for Ocean Simulation](https://www-posim.vercel.app/)
builds on POSIM, ROS 2, Gazebo, and ArduPilot to bring maritime simulation to a
web browser and a standalone application. Choose a geographic starting point,
explore real terrain with surface or underwater robots, inspect live sensor data,
and test waypoint missions or your own ROS 2 autonomy code. Visit the platform
to watch the live voyage, explore its features, and find downloads and tutorials.

```bash
python3 -m venv ~/.venvs/posim-dev
source ~/.venvs/posim-dev/bin/activate
python3 -m pip install pre-commit
pre-commit install
pre-commit run --all-files
```


## License
## Contributing

POSIM-authored source uses [Apache License 2.0](LICENSE). Existing third-party
notices remain with their source files and assets. Docker builds also install
external Wave Sim under its upstream GPL terms, retaining corresponding source
and notices; the whole image is not licensed under Apache-2.0 alone. See
[dependency and distribution details](extras/surface/README.md#submodules-and-licensing).
Report issues or propose changes in [IOES-Lab/POSIM](https://github.com/IOES-Lab/POSIM).
See the [contribution guide](https://ioes-lab.github.io/POSIM/contributing.html)
for development checks and documentation updates.

## Waves and optional surface drones
## Origins and license

The normal Docker image builds and Ubuntu stack installer automatically fetch and build the pinned external wave plugin. [WAM-V / ArduRover](extras/surface/README.md) remains an opt-in vehicle overlay. This redesign references PR #7 while keeping the wave solver in its upstream repository and preserving the regular BlueROV2 launch defaults.
POSIM continues the [DAVE](https://github.com/IOES-Lab/dave) codebase, originally
developed as [Project DAVE](https://github.com/Field-Robotics-Lab/dave), and
preserves its source history and copyright notices.
POSIM-authored source uses [Apache License 2.0](LICENSE). Third-party source and
assets retain their original terms. External Wave Sim is built from its upstream
repository under GPL terms; see the
[wave dependency and distribution details](extras/surface/README.md#submodules-and-licensing).
6 changes: 5 additions & 1 deletion website/content/en/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

POSIM is a ROS 2 and Gazebo library for maritime robotics. Combine ocean environments, vehicle descriptions, simulated sensors and control interfaces to build repeatable experiments.

## Try WWW-POSIM

[WWW-POSIM — World Wide Web Platform for Ocean Simulation](https://www-posim.vercel.app/) builds on POSIM, ROS 2, Gazebo and ArduPilot to bring maritime simulation to a web browser and a standalone application. Choose a geographic starting point, explore real terrain with surface or underwater robots, inspect live sensor data, and test waypoint missions or your own ROS 2 autonomy code. Visit the platform to watch the live voyage, explore its features, and find downloads and tutorials.

## Start here

<div class="docs-architecture"><a href="install.html"><strong>Install</strong><span>Build the ROS 2 and Gazebo workspace on Ubuntu.</span></a><a href="quickstart.html"><strong>Run</strong><span>Start an ocean world and receive your first sensor data.</span></a><a href="custom-robots.html"><strong>Extend</strong><span>Add your robot, terrain and control code.</span></a></div>
Expand All @@ -22,7 +26,7 @@ Use [Ubuntu installation](install.md) for a native Linux workspace, or [Docker](

A world SDF defines the environment and world systems. A model SDF defines links, collisions, inertia, sensors and model systems. Launch files start Gazebo, spawn the selected description and configure ROS bridges. Your ROS node reads observations and publishes commands through the configured interface.

POSIM is the simulation library. Account management, online sessions and the WWW-POSIM web platform are separate applications built around it. You can use this library directly from a ROS workspace without either service.
You can use POSIM directly from a ROS workspace. WWW-POSIM adds geographic world generation, a browser interface, account management and online sessions around the simulation library.

## Find the right guide

Expand Down
6 changes: 5 additions & 1 deletion website/content/ko/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

POSIM은 해양 로봇 실험을 위한 ROS 2·Gazebo 라이브러리입니다. 해양 환경, 로봇 모델, 모의 센서와 제어 인터페이스를 조합하여 같은 조건의 실험을 반복할 수 있습니다.

## WWW-POSIM 체험하기

[WWW-POSIM — World Wide Web Platform for Ocean Simulation](https://www-posim.vercel.app/)은 POSIM, ROS 2, Gazebo와 ArduPilot을 기반으로 웹 브라우저와 설치형 앱에서 해양 로봇 시뮬레이션을 제공하는 플랫폼입니다. 위도·경도로 시작 위치를 정하고 실제 지형에서 수상·수중 로봇을 운항하며, 실시간 센서 데이터를 확인하고 웨이포인트 임무나 직접 작성한 ROS 2 자율운항 코드를 시험할 수 있습니다. 플랫폼에서 세계 일주 라이브 항해와 주요 기능을 살펴보고, 설치 파일과 튜토리얼을 확인해 보세요.

## 여기서 시작하세요

<div class="docs-architecture"><a href="install.html"><strong>설치</strong><span>Ubuntu에 ROS 2·Gazebo 작업 공간을 구성합니다.</span></a><a href="quickstart.html"><strong>실행</strong><span>해양 월드를 띄우고 첫 센서 데이터를 받습니다.</span></a><a href="custom-robots.html"><strong>확장</strong><span>자신의 로봇, 지형과 제어 코드를 추가합니다.</span></a></div>
Expand All @@ -22,7 +26,7 @@ Linux에 직접 설치하려면 [Ubuntu 설치](install.md)를, 독립된 실행

월드 SDF에는 환경과 월드 시스템을 정의합니다. 모델 SDF에는 링크, 충돌 형상, 관성, 센서와 모델 시스템을 정의합니다. Launch 파일이 Gazebo를 시작하고 선택한 모델을 배치한 뒤 ROS 브리지를 연결합니다. 사용자의 ROS 노드는 관측값을 받아 설정된 인터페이스로 제어 명령을 보냅니다.

POSIM은 시뮬레이션 라이브러리입니다. 계정 관리, 온라인 세션과 WWW-POSIM 웹 플랫폼은 이 라이브러리를 사용하는 별도 응용 프로그램입니다. ROS 작업 공간에서 라이브러리를 직접 사용할 때는 해당 서비스가 필요하지 않습니다.
POSIM은 ROS 작업 공간에서 직접 사용할 수 있습니다. WWW-POSIM은 이 시뮬레이션 라이브러리에 지리 좌표 기반 월드 생성, 브라우저 화면, 계정 관리와 온라인 세션을 더한 플랫폼입니다.

## 필요한 문서 찾기

Expand Down
Loading