hivebr 0.1.0__tar.gz

hivebr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elias J. R. Freitas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hivebr-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include LICENSE
+include README.md
+include RELEASING.md
+include requirements-docs.txt
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include config *.yaml *.png
+global-exclude __pycache__ *.pyc *.pyo

hivebr-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.2
+Name: hivebr
+Version: 0.1.0
+Summary: Hivebr simulator - 2D simulator and OpenLab API for single- and multi-robot (B-bot) navigation.
+Author: Elias J. R. Freitas
+License: MIT
+Project-URL: Homepage, https://github.com/eliasjof/hivebr_simulator
+Project-URL: Documentation, https://eliasjof.github.io/hivebr_simulator/
+Project-URL: Repository, https://github.com/eliasjof/hivebr_simulator
+Project-URL: Issues, https://github.com/eliasjof/hivebr_simulator/issues
+Keywords: robotics,simulation,multi-robot,swarm,navigation,path-planning,mobile-robots,pygame
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygame-ce>=2.5.0
+Requires-Dist: pygame_gui>=0.6.9
+Requires-Dist: numpy>=1.24
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: maps
+Requires-Dist: Pillow>=9.0; extra == "maps"
+Requires-Dist: scipy>=1.9; extra == "maps"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.6; extra == "plot"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
+Requires-Dist: black>=24.0; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+
+# hivebr — OpenLab Simulator
+
+[![PyPI version](https://img.shields.io/pypi/v/hivebr.svg)](https://pypi.org/project/hivebr/)
+[![Python versions](https://img.shields.io/pypi/pyversions/hivebr.svg)](https://pypi.org/project/hivebr/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/eliasjof/hivebr_simulator/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://eliasjof.github.io/hivebr_simulator/)
+
+A lightweight 2D simulation framework for **single- and multi-robot mobile
+navigation**, built on Pygame, with a dual-paradigm **OpenLab API** for
+centralized and decentralized control.
+
+Robots in the simulator are called **B-bots** (for *bee*), keeping the hive
+metaphor.
+
+📖 **Full documentation:** <https://eliasjof.github.io/hivebr_simulator/>
+
+---
+
+## Installation
+
+```bash
+pip install hivebr
+```
+
+Optional extras:
+
+```bash
+pip install "hivebr[maps]"   # occupancy grids (Pillow + scipy)
+pip install "hivebr[plot]"   # data logger plots (matplotlib)
+```
+
+## Quick start
+
+```python
+from hivebr import HiveBrAgent, SwarmExperiment
+
+class Patrol(HiveBrAgent):
+    def loop(self, state, neighbors):
+        # state.goal holds the current waypoint (x, y, theta)
+        return 0.5, 0.0
+
+exp = SwarmExperiment(robots=3, backend="navsim2d")
+exp.assign_agent(robot_ids=[0, 1, 2], agent_class=Patrol)
+exp.assign_route(0, [[5, 2, 0.0], [5, 6, 0.0]])
+exp.run()
+```
+
+A single robot is just a fleet with `N = 1`. Switching `backend="ros2"` reuses
+the same agent code on the physical arena.
+
+## Dual paradigm
+
+| Decentralized — `HiveBrAgent` | Centralized — `SwarmController` |
+| ----------------------------- | ------------------------------- |
+| One instance per B-bot | Exactly one instance |
+| Receives its `state` + `neighbors` | Receives all `states` |
+| Returns a command | Returns `{robot_id: command}` |
+| Reactive control, consensus | Global planning, optimization (DE, L-SHADE) |
+
+## Features
+
+- **Mono or fleet, one API.** A single robot is a fleet with `N = 1`.
+- **Interactive GUI.** Pan/zoom, load occupancy-grid maps, switch themes,
+  toggle LiDAR, add waypoints and obstacles with the mouse.
+- **Two environment representations.** Analytic circular obstacles *and*
+  image-based occupancy grids with inflation.
+- **Precision sensing.** Ray-casting LiDAR (DDA) against the grid plus analytic
+  circle intersections.
+- **Deterministic fleets.** Each timestep is computed from a frozen snapshot of
+  the fleet state, independent of update order.
+- **Research-ready.** Pluggable controllers, path planners (A*, RRT, RRT*, PRM,
+  BIT*, OMPL, RRT-Dubins), and a data logger for offline analysis.
+
+## Robot models
+
+| `type` | Command |
+| ------ | ------- |
+| `differential` | `{"v": ..., "omega": ...}` |
+| `differential_firstorder` | `{"v": ..., "omega": ...}` |
+| `holonomic` | `{"vx": ..., "vy": ...}` |
+| `ackermann` | `{"speed": ..., "steer": ...}` |
+| `boat` | `{"v": ..., "omega": ...}` |
+
+## Run the examples
+
+```bash
+# from a clone of the repository (examples are not shipped in the wheel)
+python examples/controle_robodiferencial.py
+python examples/decentralized_swarm.py
+python examples/multi_robot_differential.py
+```
+
+## Links
+
+- Documentation: <https://eliasjof.github.io/hivebr_simulator/>
+- Repository: <https://github.com/eliasjof/hivebr_simulator>
+- Issue tracker: <https://github.com/eliasjof/hivebr_simulator/issues>
+
+## License
+
+MIT — free for educational and research use. See [LICENSE](LICENSE).

hivebr-0.1.0/README.md

@@ -0,0 +1,101 @@
+# hivebr — OpenLab Simulator
+
+[![PyPI version](https://img.shields.io/pypi/v/hivebr.svg)](https://pypi.org/project/hivebr/)
+[![Python versions](https://img.shields.io/pypi/pyversions/hivebr.svg)](https://pypi.org/project/hivebr/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/eliasjof/hivebr_simulator/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://eliasjof.github.io/hivebr_simulator/)
+
+A lightweight 2D simulation framework for **single- and multi-robot mobile
+navigation**, built on Pygame, with a dual-paradigm **OpenLab API** for
+centralized and decentralized control.
+
+Robots in the simulator are called **B-bots** (for *bee*), keeping the hive
+metaphor.
+
+📖 **Full documentation:** <https://eliasjof.github.io/hivebr_simulator/>
+
+---
+
+## Installation
+
+```bash
+pip install hivebr
+```
+
+Optional extras:
+
+```bash
+pip install "hivebr[maps]"   # occupancy grids (Pillow + scipy)
+pip install "hivebr[plot]"   # data logger plots (matplotlib)
+```
+
+## Quick start
+
+```python
+from hivebr import HiveBrAgent, SwarmExperiment
+
+class Patrol(HiveBrAgent):
+    def loop(self, state, neighbors):
+        # state.goal holds the current waypoint (x, y, theta)
+        return 0.5, 0.0
+
+exp = SwarmExperiment(robots=3, backend="navsim2d")
+exp.assign_agent(robot_ids=[0, 1, 2], agent_class=Patrol)
+exp.assign_route(0, [[5, 2, 0.0], [5, 6, 0.0]])
+exp.run()
+```
+
+A single robot is just a fleet with `N = 1`. Switching `backend="ros2"` reuses
+the same agent code on the physical arena.
+
+## Dual paradigm
+
+| Decentralized — `HiveBrAgent` | Centralized — `SwarmController` |
+| ----------------------------- | ------------------------------- |
+| One instance per B-bot | Exactly one instance |
+| Receives its `state` + `neighbors` | Receives all `states` |
+| Returns a command | Returns `{robot_id: command}` |
+| Reactive control, consensus | Global planning, optimization (DE, L-SHADE) |
+
+## Features
+
+- **Mono or fleet, one API.** A single robot is a fleet with `N = 1`.
+- **Interactive GUI.** Pan/zoom, load occupancy-grid maps, switch themes,
+  toggle LiDAR, add waypoints and obstacles with the mouse.
+- **Two environment representations.** Analytic circular obstacles *and*
+  image-based occupancy grids with inflation.
+- **Precision sensing.** Ray-casting LiDAR (DDA) against the grid plus analytic
+  circle intersections.
+- **Deterministic fleets.** Each timestep is computed from a frozen snapshot of
+  the fleet state, independent of update order.
+- **Research-ready.** Pluggable controllers, path planners (A*, RRT, RRT*, PRM,
+  BIT*, OMPL, RRT-Dubins), and a data logger for offline analysis.
+
+## Robot models
+
+| `type` | Command |
+| ------ | ------- |
+| `differential` | `{"v": ..., "omega": ...}` |
+| `differential_firstorder` | `{"v": ..., "omega": ...}` |
+| `holonomic` | `{"vx": ..., "vy": ...}` |
+| `ackermann` | `{"speed": ..., "steer": ...}` |
+| `boat` | `{"v": ..., "omega": ...}` |
+
+## Run the examples
+
+```bash
+# from a clone of the repository (examples are not shipped in the wheel)
+python examples/controle_robodiferencial.py
+python examples/decentralized_swarm.py
+python examples/multi_robot_differential.py
+```
+
+## Links
+
+- Documentation: <https://eliasjof.github.io/hivebr_simulator/>
+- Repository: <https://github.com/eliasjof/hivebr_simulator>
+- Issue tracker: <https://github.com/eliasjof/hivebr_simulator/issues>
+
+## License
+
+MIT — free for educational and research use. See [LICENSE](LICENSE).

hivebr-0.1.0/RELEASING.md

@@ -0,0 +1,85 @@
+# Releasing hivebr
+
+This project publishes to [PyPI](https://pypi.org/project/hivebr/) as `hivebr`.
+
+## 1. Bump the version
+
+Edit `version` in `pyproject.toml` (semantic versioning, e.g. `0.1.1`, `0.2.0`).
+Keep `hivebr.__version__` in `src/hivebr/__init__.py` in sync.
+
+## 2. Build locally and check the metadata
+
+```bash
+python -m pip install -U build twine
+python -m build
+python -m twine check dist/*
+```
+
+`python -m build` produces:
+
+- `dist/hivebr-<version>.tar.gz` (sdist)
+- `dist/hivebr-<version>-py3-none-any.whl` (wheel)
+
+Inspect the wheel to confirm the engine assets and subpackages are present:
+
+```bash
+python -m zipfile -l dist/hivebr-*.whl
+```
+
+## 3. Test the wheel in a clean environment
+
+```bash
+python -m venv /tmp/hivebr-test
+# Windows: /tmp/hivebr-test/Scripts/activate ; Linux/macOS:
+source /tmp/hivebr-test/bin/activate
+pip install dist/hivebr-*.whl
+python -c "import hivebr; print(hivebr.__version__)"
+python -c "from hivebr.engine import Simulator; print('engine ok')"
+```
+
+## 4. Publish
+
+### Option A — Automated (recommended, Trusted Publishing)
+
+Pushing a GitHub **release** (or running the `Publish to PyPI` workflow
+manually) triggers `.github/workflows/Publish.yml`, which builds and uploads the
+distributions.
+
+One-time setup on PyPI:
+
+1. Go to **PyPI → Your projects → Publishing** (or
+   <https://pypi.org/manage/account/publishing/>).
+2. Add a **pending publisher** / trusted publisher with:
+   - PyPI project name: `hivebr`
+   - Owner: `eliasjof`
+   - Repository: `hivebr_simulator`
+   - Workflow name: `Publish.yml`
+   - Environment name: `pypi`
+3. Create a GitHub **environment** named `pypi` (Settings → Environments).
+
+No API token is required.
+
+### Option B — Manual
+
+```bash
+python -m twine upload dist/*
+```
+
+Use an API token (`__token__` as username) when prompted, or set `TWINE_USERNAME`
+and `TWINE_PASSWORD` (or a `~/.pypirc`) beforehand.
+
+## 5. Tag the release
+
+```bash
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+## Checklist
+
+- [ ] Version bumped in `pyproject.toml` and `src/hivebr/__init__.py`
+- [ ] `python -m build` succeeds
+- [ ] `python -m twine check dist/*` passes
+- [ ] Wheel imports fine in a clean venv
+- [ ] Docs build (`mkdocs build --strict`)
+- [ ] GitHub release created (triggers the publish workflow)

hivebr-0.1.0/config/default copy.yaml

@@ -0,0 +1,127 @@
+window:
+  width: 1400
+  height: 750
+  min_width: 1100
+  min_height: 650
+  panel_width: 300
+  title: HiveBr Simulator
+world:
+  width: 20.0
+  height: 12.0
+  grid_size: 1.0
+  obstacle_radius: 0.4
+  show_origin: true
+  show_axes: true
+  default_obstacle_radius: 0.4
+  obstacles:
+  - - 6.0
+    - 5.0
+    - 1.2
+  - - 13.163636363636364
+    - 5.709090909090909
+    - 0.4
+camera:
+  initial_zoom: 1.0
+  min_zoom: 0.25
+  max_zoom: 8.0
+  zoom_step: 1.1
+  margin_x: 1.0
+  margin_y: 1.0
+robot:
+  type: differential
+  initial_pose:
+  - 2.0
+  - 2.0
+  - 0.0
+  radius: 0.4473
+  length: 0.8
+  width: 0.4
+  wheel_base: 0.5
+  max_speed: 3.0
+  max_omega: 4.0
+  max_steer: 0.52
+  path_max_length: 4000
+lidar:
+  enabled: true
+  num_rays: 101
+  range: 12.0
+  fov_deg: 360
+waypoints:
+  goal_tolerance: 0.5
+controller:
+  enabled: true
+  attractive_gain: 1.0
+  repulsive_gain: 2.0
+  repulsive_radius: 5.0
+  max_repulsive_force: 8.0
+  force_filter_alpha: 0.35
+  command_filter_alpha: 0.4
+  obstacle_slowdown_distance: 2.0
+  min_obstacle_speed_factor: 0.2
+  min_lidar_distance: 0.08
+  linear_gain: 0.6
+  angular_gain: 0.6
+  max_steer_rate: 0.52
+  curvature_speed_gain: 2.0
+  tangential_gain: 1.5          # k_tang — MOD-3
+  stagnation_radius: 0.15       # metros — MOD-1
+  local_minima_angle_deg: 90.0  # graus — MOD-1
+  virtual_subgoal_offset: 2.0   # metros — MOD-2
+  emergency_brake_distance: 0.5   # metros — aciona BRAKE
+  emergency_safe_distance:  0.65   # metros — cancela BRAKE se obstáculo recua
+  emergency_rear_clearance: 0.50   # metros — interrompe ré se obstáculo atrás
+  reverse_speed:           -0.25   # m/s — velocidade da ré (negativo)
+  reverse_duration_s:       1.2    # segundos — duração máxima da ré
+colors:
+  background:
+  - 30
+  - 30
+  - 30
+  grid:
+  - 50
+  - 50
+  - 50
+  panel:
+  - 20
+  - 20
+  - 20
+  robot:
+  - 220
+  - 50
+  - 50
+  obstacle:
+  - 50
+  - 100
+  - 255
+  waypoint:
+  - 255
+  - 220
+  - 0
+  goal:
+  - 0
+  - 255
+  - 0
+  path:
+  - 255
+  - 140
+  - 0
+  lidar:
+  - 0
+  - 255
+  - 255
+  red:
+  - 220
+  - 50
+  - 50
+  green:
+  - 0
+  - 255
+  - 0
+  white:
+  - 255
+  - 255
+  - 255
+  black:
+  - 0
+  - 0
+  - 0

hivebr-0.1.0/config/default.yaml

@@ -0,0 +1,147 @@
+window:
+  width: 1400
+  height: 750
+  min_width: 1100
+  min_height: 650
+  panel_width: 300
+  title: HiveBr Simulator
+world:
+  width: 20.0
+  height: 12.0
+  grid_size: 1.0
+  obstacle_radius: 0.4
+  show_origin: true
+  show_axes: true
+  default_obstacle_radius: 0.4
+  obstacles:
+  - - 6.381818181818182
+    - 5.3090909090909095
+    - 0.4  
+  resolution: 0.1
+camera:
+  initial_zoom: 1.0
+  min_zoom: 0.25
+  max_zoom: 8.0
+  zoom_step: 1.1
+  margin_x: 1.0
+  margin_y: 1.0
+robot:
+  type: differential
+  initial_pose:
+  - 2.5
+  - 2.5
+  - 0.0
+  radius: 0.1375
+  length: 0.39
+  width: 0.275
+  wheel_base: 0.285
+  max_speed: 3.0
+  max_omega: 4.0
+  max_steer: 0.52
+  tau_v: 0.2
+  path_max_length: 4000
+lidar:
+  enabled: false
+  num_rays: 101
+  range: 12.0
+  fov_deg: 360
+waypoints:
+  goal_tolerance: 0.5
+  define_orientation: true
+  show_tolerance_circle: false
+  points: []
+controller:
+  enabled: true
+  attractive_gain: 1.0
+  repulsive_gain: 2.0
+  repulsive_radius: 2.0
+  max_repulsive_force: 8.0
+  force_filter_alpha: 0.35
+  command_filter_alpha: 0.4
+  obstacle_slowdown_distance: 2.0
+  min_obstacle_speed_factor: 0.2
+  min_lidar_distance: 0.08
+  linear_gain: 0.6
+  angular_gain: 0.6
+  max_steer_rate: 0.52
+  curvature_speed_gain: 2.0
+  tangential_gain: 1.5
+  stagnation_radius: 0.15
+  local_minima_angle_deg: 90.0
+  virtual_subgoal_offset: 2.0
+  emergency_brake_distance: 0.5
+  emergency_safe_distance: 0.65
+  emergency_rear_clearance: 0.5
+  reverse_speed: -0.25
+  reverse_duration_s: 1.2
+colors:
+  background:
+  - 240
+  - 240
+  - 240
+  grid:
+  - 220
+  - 220
+  - 220
+  panel:
+  - 20
+  - 20
+  - 20
+  robot:
+  - 30
+  - 144
+  - 255
+  obstacle:
+  - 0
+  - 100
+  - 0
+  waypoint:
+  - 180
+  - 150
+  - 0
+  goal:
+  - 140
+  - 0
+  - 255
+  path:
+  - 30
+  - 144
+  - 255
+  lidar:
+  - 0
+  - 150
+  - 150
+  red:
+  - 200
+  - 0
+  - 0
+  green:
+  - 0
+  - 150
+  - 0
+  white:
+  - 0
+  - 0
+  - 0
+  black:
+  - 255
+  - 255
+  - 255
+  silver:
+  - 192
+  - 192
+  - 186
+  occupancy_inflated:
+  - 50
+  - 129
+  - 75
+  occupancy_raw:
+  - 40
+  - 120
+  - 40
+  occupancy_free:
+  - 230
+  - 230
+  - 230
+obstacles: []
+theme: light