yeseorizi · Mar 16, 2026 · Mar 16, 2026 · Mar 18, 2026 · Mar 18, 2026 · Apr 13, 2026
diff --git a/.docker/lyrical.arm64v8.dockerfile b/.docker/lyrical.arm64v8.dockerfile
@@ -6,7 +6,7 @@
 #   setup below is the adapted version of what that base image contained, plus the xrdp
 #   group-permission fix required by the verified Apple Silicon build.
 # - ROS_DISTRO=lyrical; ros-lyrical-ros-gz supplies the Gazebo Jetty vendor packages.
-# - The current CUDA sonar remains disabled on ARM64; the open WGPU PR is intentionally excluded.
+# - The sonar uses the portable WGPU backend when CUDA is unavailable on ARM64.
 # - ArduSub SITL includes the Python 3.14 compatibility shims validated on Ubuntu 26.04
 #   (imp/pipes modules, python-argparse removal, and PEP 668 handling).
 
@@ -96,13 +96,15 @@ EXPOSE 22/tcp
 
 # --- ROS 2 Lyrical + Gazebo Jetty ---
 ARG ROS_DISTRO="lyrical"
+ARG ROS_APT_SOURCE_VERSION="1.3.0"
 ENV GZ_VERSION=jetty
 
 RUN apt update && apt full-upgrade -y && apt autoremove -y
 
 # Gazebo Jetty is vendored by ros-lyrical-ros-gz on apt already — no separate Gazebo source build
-RUN export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F\" '{print $4}') && \
-    curl -L -o /tmp/ros2-apt-source.deb \
+# Pin the bootstrap package to avoid unauthenticated GitHub API rate limits.
+RUN curl --fail --show-error --location --retry 5 --retry-delay 2 \
+      -o /tmp/ros2-apt-source.deb \
       "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}})_all.deb" && \
     dpkg -i /tmp/ros2-apt-source.deb && \
     apt update && \

diff --git a/README.md b/README.md
@@ -19,6 +19,14 @@ 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).
 
+## Multibeam sonar
+
+Run the BlueView P900 sensor with WGPU, CUDA or CPU processing. Select the backend
+at launch and inspect sonar images, raw acoustic data and point clouds.
+
+- English: [sensor and demo](website/content/en/sonar.md), [build and backend setup](website/content/en/sonar-tuning.md), [Apple Silicon](website/content/en/sonar-tuning.md#apple-silicon)
+- 한국어: WGPU·CUDA·CPU 계산 방식을 선택하여 소나 영상·원시 음향 데이터·점군을 확인합니다. [센서와 예제](website/content/ko/sonar.md), [빌드와 계산 설정](website/content/ko/sonar-tuning.md), [Apple Silicon](website/content/ko/sonar-tuning.md#apple-silicon)
+
 ## Try WWW-POSIM
 
 [WWW-POSIM](https://www-posim.vercel.app/) uses POSIM as its simulation engine.

diff --git a/docs/engineering/sonar-public-documentation.md b/docs/engineering/sonar-public-documentation.md
@@ -0,0 +1,40 @@
+# Sonar public documentation evidence
+
+## Source snapshot
+
+- POSIM sonar PR: https://github.com/IOES-Lab/POSIM/pull/6
+- Source head: `ad6165bd6c2b4e407f18ecb264e20bb76da8d4ca`.
+- Input guides: `gazebo/DEMO_GUIDE.md` and `gazebo/DEMO_GUIDE_AppleSilicon_MacOSX.md`.
+- Runtime report: https://github.com/IOES-Lab/POSIM/pull/6#issuecomment-6135206430.
+- User clarified that these documentation changes belong in PR #6; PR #7 is the closed ocean-waves contribution.
+
+## Source-backed user behavior
+
+- `sonar_compute_cpu.cc`: `auto` tries CUDA, WGPU, CPU; explicit failures and invalid names return no backend.
+- `MultibeamSonarSensor.cc`: environment name is `POSIM_SONAR_COMPUTE_BACKEND`; publishes Image and ProjectedSonarImage directly to ROS 2, and PointCloudPacked over Gazebo transport; rendering is required for GpuRays.
+- Demo launch: declares `compute_backend` (default `auto`) and `rviz`, and sets the POSIM backend environment variable.
+- Sonar CMake: WGPU is required, CUDA is optional, `CUDA_ARCHITECTURE` defaults to `native` and forwards to `CMAKE_CUDA_ARCHITECTURES`; Apple builds link Metal/QuartzCore.
+- Rust pipeline: Vulkan is the Linux default, Metal is the macOS default; supports adapter substring, backend API and power-preference selection; GPU context is shared in-process.
+- WGPU 0.20.1 power-preference values checked against https://github.com/gfx-rs/wgpu/blob/v0.20.1/wgpu/src/util/init.rs: `high`, `low`, `none`.
+
+## Documentation decisions
+
+Public pages describe present behavior and commands. The two demo files and sonar README point to the authoritative English/Korean guides. Root README and installation, requirements, overview and troubleshooting pages use the same supported backend facts.
+
+The inherited demo guides refer to Ubuntu 24.04/ROS Rolling and macOS Jazzy/Harmonic setup. These version-specific setup commands are not copied into Lyrical/Jetty instructions. Native macOS instructions state the matching ROS/Gazebo/rendering prerequisites; they are not a turnkey host installer or a fresh native runtime validation.
+
+The contributor reports Ubuntu 26.04.1, ROS 2 Lyrical, Gazebo 10.5.0, RTX 4060 and Intel iGPU runtime tests. Reported panel range errors at 2–8 m and 0–45 degrees were approximately 0.03–0.05 m for WGPU and 0.03–0.06 m for CUDA, with 2.5 cm range bins. These are attributed test observations, not new measurements by this documentation change or public accuracy guarantees.
+
+The public text omits migration history, commit counts, implementation cleanup, shared-buffer allocation counts and before/after comparisons. Build/check and browser review results are recorded separately from user instructions.
+
+## Documentation validation
+
+- Node.js 24: `pnpm catalog`, `pnpm build`, `pnpm check`.
+- Full repository check: 50 pages, 3,575 local links/anchors, 38 bilingual public media, bilingual search and 42 source launch references.
+- Website-only build/check passes without the ROS/model source tree.
+- EN/KO command blocks match for sonar, sonar tuning, installation, requirements, overview and troubleshooting. Sonar Bash blocks pass `bash -n`.
+- Both demo wrappers pass the public-wording checker. `git diff --check` passes.
+- WebKit desktop (1440 x 1000) and mobile (390 x 844) checks cover both sonar pages in both languages: no document overflow or JavaScript page errors, and language switching passes.
+- Desktop Apple Silicon section and Korean mobile demo output visually inspected. Browser captures/results are local ignored files under `website/.validation/sonar/`.
+- Website documentation-basis metadata uses the inspected PR source snapshot; no Notion review date or source media metadata is changed.
+- These are documentation checks. This change does not claim a new sonar simulation run or a native Apple Silicon build.
diff --git a/extras/ros-lyrical-gz-jetty-install.sh b/extras/ros-lyrical-gz-jetty-install.sh
@@ -59,8 +59,10 @@ sudo apt update && sudo apt install -y jq
 # shellcheck disable=SC1091
 . /etc/os-release
 UBUNTU_CODENAME="${UBUNTU_CODENAME:-${VERSION_CODENAME}}"
-ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | jq -r '.tag_name') && \
-    curl -L -o /tmp/ros2-apt-source.deb \
+# Use a known release instead of a rate-limited unauthenticated API lookup.
+ROS_APT_SOURCE_VERSION="${ROS_APT_SOURCE_VERSION:-1.3.0}"
+curl --fail --show-error --location --retry 5 --retry-delay 2 \
+    -o /tmp/ros2-apt-source.deb \
     "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.${UBUNTU_CODENAME}_all.deb" && \
     sudo apt-get install -y /tmp/ros2-apt-source.deb && \
     rm -f /tmp/ros2-apt-source.deb

diff --git a/gazebo/DEMO_GUIDE.md b/gazebo/DEMO_GUIDE.md
@@ -0,0 +1,12 @@
+# Multibeam sonar demo
+
+Run the BlueView P900 demo with WGPU, CUDA or CPU processing. The public guides
+cover build prerequisites, launch commands, backend selection, output topics
+and troubleshooting.
+
+- English: [run the demo](../website/content/en/sonar.md), [build and backend setup](../website/content/en/sonar-tuning.md)
+- 한국어: [소나 예제 실행](../website/content/ko/sonar.md), [빌드와 계산 설정](../website/content/ko/sonar-tuning.md)
+
+POSIM uses ROS 2 Lyrical and Gazebo Jetty. Start with the
+[installation guide](../website/content/en/install.md) or
+[한국어 설치 안내](../website/content/ko/install.md), then follow the sonar guides above.
diff --git a/gazebo/DEMO_GUIDE_AppleSilicon_MacOSX.md b/gazebo/DEMO_GUIDE_AppleSilicon_MacOSX.md
@@ -0,0 +1,11 @@
+# Multibeam sonar on Apple Silicon
+
+The public sonar build guide covers Metal for native macOS and CPU acoustic
+processing in a Linux ARM64 container. Both require Gazebo rendering and a
+matching ROS 2 / Gazebo environment.
+
+- English: [Apple Silicon setup](../website/content/en/sonar-tuning.md#apple-silicon), [sensor and demo](../website/content/en/sonar.md)
+- 한국어: [Apple Silicon 설정](../website/content/ko/sonar-tuning.md#apple-silicon), [센서와 예제](../website/content/ko/sonar.md)
+
+Use the [Docker guide](../website/content/en/docker.md) or
+[한국어 Docker 안내](../website/content/ko/docker.md) for a Linux ARM64 environment.
diff --git a/gazebo/posim_gz_multibeam_sonar/README.md b/gazebo/posim_gz_multibeam_sonar/README.md
@@ -1,20 +1,25 @@
 # POSIM multibeam sonar
 
-The ray-based point-scattering model produces intensity/range data, with
-phase, reverberation and speckle effects.
+The ray-based point-scattering model produces intensity–range data, sonar images
+and point clouds. Select WGPU, CUDA or CPU processing at launch. WGPU uses Vulkan
+on Linux and Metal on native macOS; all backends require Gazebo rendering.
 
-## Backend requirements
+## Documentation
 
-- ROS 2 Lyrical and Gazebo Jetty
-- Compatible NVIDIA GPU and CUDA toolkit
-- Built CUDA sonar libraries
+- [Sensor, demo and output topics](../../website/content/en/sonar.md)
+- [Build, backend selection and troubleshooting](../../website/content/en/sonar-tuning.md)
+- [Apple Silicon](../../website/content/en/sonar-tuning.md#apple-silicon)
+- [POSIM installation](../../website/content/en/install.md)
+- [Research citation and licenses](../../website/content/en/citation.md)
 
-CMake skips CUDA targets when the toolkit is unavailable. Check library
-installation and sensor output with the [sonar build guide](../../website/content/en/sonar-tuning.md).
+## 한국어 안내
 
-## Documentation
+광선 기반 점 산란 모델로 강도·거리 데이터, 소나 영상과 점군을 생성합니다.
+실행할 때 WGPU·CUDA·CPU 계산 방식을 선택합니다. WGPU는 Linux에서 Vulkan,
+macOS에서 직접 실행할 때 Metal을 사용합니다. 모든 방식에서 Gazebo 렌더링이 필요합니다.
 
-See the [POSIM sonar guide](../../website/content/en/sonar.md)
-for the model and configuration. Use the
-[POSIM installation guide](../../website/content/en/install.md) for current repository
-and workspace setup.
+- [센서·예제·출력 토픽](../../website/content/ko/sonar.md)
+- [빌드·계산 방식·문제 해결](../../website/content/ko/sonar-tuning.md)
+- [Apple Silicon](../../website/content/ko/sonar-tuning.md#apple-silicon)
+- [POSIM 설치](../../website/content/ko/install.md)
+- [연구 인용과 라이선스](../../website/content/ko/citation.md)
diff --git a/gazebo/posim_gz_multibeam_sonar/multibeam_sonar/CMakeLists.txt b/gazebo/posim_gz_multibeam_sonar/multibeam_sonar/CMakeLists.txt
@@ -1,74 +1,105 @@
 cmake_minimum_required(VERSION 3.11.0 FATAL_ERROR)
 
 # Suppress developer warnings for the entire workspace.
-
 set(CMAKE_SUPPRESS_DEVELOPER_WARNINGS TRUE CACHE BOOL
     "Suppress developer warnings" FORCE)
-# Set CMP0144 to NEW to ensure find_package
-# uses upper-case <PACKAGENAME>_ROOT variables.
 
+# Ensure find_package uses upper-case <PACKAGENAME>_ROOT variables.
 cmake_policy(SET CMP0144 NEW)
 
-project(multibeam_sonar)
+set(CUDA_ARCHITECTURE "native" CACHE STRING
+    "Target CUDA SM version(s), e.g. native or 70;80;89")
+set(CMAKE_CUDA_ARCHITECTURES "${CUDA_ARCHITECTURE}")
 
-set(CUDA_ARCHITECTURE "60" CACHE STRING "Target CUDA SM version")
+project(multibeam_sonar)
 
 find_package(ament_cmake REQUIRED)
+find_package(gz-cmake 5 REQUIRED)
+find_package(gz-sim 10 REQUIRED)
+find_package(gz-sensors 10 REQUIRED)
+find_package(gz-rendering 10 REQUIRED OPTIONAL_COMPONENTS ogre ogre2)
+find_package(gz-transport 15 REQUIRED)
+find_package(gz-msgs 12 REQUIRED)
+find_package(rclcpp REQUIRED)
+find_package(sensor_msgs REQUIRED)
+find_package(geometry_msgs REQUIRED)
+find_package(OpenCV REQUIRED)
+find_package(marine_acoustic_msgs REQUIRED)
+find_package(Eigen3 REQUIRED)
+find_package(wgpu_vendor REQUIRED)
 find_package(CUDAToolkit QUIET)
 
 if(CUDAToolkit_FOUND)
-
+  set(CMAKE_CUDA_COMPILER "${CUDAToolkit_NVCC_EXECUTABLE}"
+      CACHE FILEPATH "CUDA compiler" FORCE)
   enable_language(CUDA)
   find_package(CUDA REQUIRED)
-  message(STATUS "CUDA found, enabling CUDA support.")
+  message(STATUS
+    "CUDA ${CUDAToolkit_VERSION} found (SM ${CUDA_ARCHITECTURE}), "
+    "enabling CUDA support.")
   include_directories(${CUDA_INCLUDE_DIRS})
-  set(CUDA_NVCC_FLAGS "${CUDA_NVCC_FLAGS} -arch=sm_${CUDA_ARCHITECTURE}")
-  find_package(tinyxml2 CONFIG REQUIRED)
-  find_package(gz-cmake 5 REQUIRED)
-  find_package(gz-sim 10 REQUIRED)
-  find_package(gz-sensors 10 REQUIRED)
-  find_package(gz-rendering 10 REQUIRED OPTIONAL_COMPONENTS ogre ogre2)
-  find_package(gz-transport 15 REQUIRED)
-  find_package(gz-msgs 12 REQUIRED)
-  find_package(rclcpp REQUIRED)
-  find_package(sensor_msgs REQUIRED)
-  find_package(geometry_msgs REQUIRED)
-  find_package(rosidl_default_generators REQUIRED)
-  find_package(OpenCV REQUIRED)
-  find_package(marine_acoustic_msgs REQUIRED)
-  find_package(cv_bridge REQUIRED)
-
-  if(TARGET gz-rendering::ogre)
-    set(HAVE_OGRE TRUE)
-    add_definitions(-DWITH_OGRE)
-  endif()
+endif()
 
-  if(TARGET gz-rendering::ogre2)
-    set(HAVE_OGRE2 TRUE)
-    add_definitions(-DWITH_OGRE2)
-  endif()
+if(TARGET gz-rendering::ogre)
+  add_definitions(-DWITH_OGRE)
+endif()
 
-  add_library(${PROJECT_NAME}
-    SHARED
-      MultibeamSonarSensor.cc
-      sonar_calculation_cuda.cu
-  )
+if(TARGET gz-rendering::ogre2)
+  add_definitions(-DWITH_OGRE2)
+endif()
+
+set(SONAR_SOURCES
+  MultibeamSonarSensor.cc
+  sonar_compute_cpu.cc
+  sonar_compute_wgpu.cc
+  sonar_compute_cuda.cc
+)
+
+if(CUDAToolkit_FOUND)
+  list(APPEND SONAR_SOURCES sonar_calculation_cuda.cu)
+endif()
 
+add_library(${PROJECT_NAME} SHARED ${SONAR_SOURCES})
+
+if(CUDAToolkit_FOUND)
   set_target_properties(${PROJECT_NAME}
     PROPERTIES
-    CUDA_SEPARABLE_COMPILATION ON
+      CUDA_SEPARABLE_COMPILATION ON
   )
+  target_compile_definitions(${PROJECT_NAME} PRIVATE POSIM_HAS_CUDA_BACKEND=1)
+endif()
 
-  target_include_directories(${PROJECT_NAME}
-    PUBLIC
-    ${gz-sensors_INCLUDE_DIRS}
-    ${gz-rendering_INCLUDE_DIRS}
-    ${gz-msgs_INCLUDE_DIRS}
-    ${CUDA_INCLUDE_DIRS}
-    ${gz-transport_INCLUDE_DIRS}
-    ${gz-sim_INCLUDE_DIRS}
+target_include_directories(${PROJECT_NAME} PUBLIC
+  ${rclcpp_INCLUDE_DIRS}
+  ${sensor_msgs_INCLUDE_DIRS}
+  ${geometry_msgs_INCLUDE_DIRS}
+  ${OpenCV_INCLUDE_DIRS}
+  ${EIGEN3_INCLUDE_DIRS}
+  ${marine_acoustic_msgs_INCLUDE_DIRS}
+)
+
+target_link_libraries(${PROJECT_NAME}
+  gz-sim::gz-sim
+  gz-sensors::gz-sensors
+  gz-msgs::gz-msgs
+  gz-transport::gz-transport
+  gz-rendering::gz-rendering
+  ${rclcpp_LIBRARIES}
+  ${sensor_msgs_LIBRARIES}
+  ${geometry_msgs_LIBRARIES}
+  ${OpenCV_LIBS}
+  Eigen3::Eigen
+  ${marine_acoustic_msgs_LIBRARIES}
+)
+
+if(APPLE)
+  target_link_libraries(${PROJECT_NAME}
+    "-framework Metal"
+    "-framework QuartzCore"
   )
+endif()
 
+if(CUDAToolkit_FOUND)
   find_library(CUBLAS_LIB cublas
     HINTS
       ${CUDAToolkit_LIBRARY_DIR}
@@ -79,43 +110,44 @@ if(CUDAToolkit_FOUND)
   if(NOT CUBLAS_LIB)
     message(FATAL_ERROR "cuBLAS not found")
   endif()
-
   target_link_libraries(${PROJECT_NAME}
-    gz-sim::gz-sim
-    gz-sensors::gz-sensors
-    gz-msgs::gz-msgs
-    gz-transport::gz-transport
-    gz-rendering::gz-rendering
     ${CUDA_LIBRARIES}
     ${CUDA_CUFFT_LIBRARIES}
     ${CUBLAS_LIB}
   )
+endif()
 
-  if(TARGET gz-sensors::gz-sensors-rendering)
-    target_link_libraries(${PROJECT_NAME} gz-sensors::gz-sensors-rendering)
-  endif()
+set(_wgpu_target_linked FALSE)
+if(TARGET wgpu::wgpu_vendor)
+  target_link_libraries(${PROJECT_NAME} wgpu::wgpu_vendor)
+  set(_wgpu_target_linked TRUE)
+elseif(TARGET wgpu_vendor)
+  target_link_libraries(${PROJECT_NAME} wgpu_vendor)
+  set(_wgpu_target_linked TRUE)
+endif()
 
-  install(TARGETS ${PROJECT_NAME}
-    DESTINATION lib/${PROJECT_NAME}
-  )
+# Ensure the Rust static archive is linked into this shared library. The
+# exported interface target may not always propagate non-installed imported
+# targets across package boundaries in overlay builds.
+if(NOT _wgpu_target_linked AND DEFINED wgpu_vendor_DIR)
+  get_filename_component(
+    _wgpu_vendor_prefix "${wgpu_vendor_DIR}/../../.." ABSOLUTE)
+  set(_sonar_wgpu_static "${_wgpu_vendor_prefix}/lib/libsonar_wgpu.a")
+  if(EXISTS "${_sonar_wgpu_static}")
+    target_link_libraries(${PROJECT_NAME} "${_sonar_wgpu_static}")
+  endif()
+endif()
 
-  ament_target_dependencies(${PROJECT_NAME}
-    rclcpp
-    sensor_msgs
-    rosidl_default_generators
-    OpenCV
-    marine_acoustic_msgs
-    geometry_msgs
-    cv_bridge
-  )
+if(TARGET gz-sensors::gz-sensors-rendering)
+  target_link_libraries(${PROJECT_NAME} gz-sensors::gz-sensors-rendering)
+endif()
 
-  ament_environment_hooks(
-    "${CMAKE_CURRENT_SOURCE_DIR}/hooks/${PROJECT_NAME}.dsv.in"
-  )
+install(TARGETS ${PROJECT_NAME}
+  DESTINATION lib/${PROJECT_NAME}
+)
 
-else()
-  message(STATUS "CUDA Toolkit not found or disabled: "
-                "Skipping CUDA-specific targets")
-endif()
+ament_environment_hooks(
+  "${CMAKE_CURRENT_SOURCE_DIR}/hooks/${PROJECT_NAME}.dsv.in"
+)
 
 ament_package()