# n-haru0524/one architecture

> Architecture diagram of the GitHub repository n-haru0524/one, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/n-haru0524/one
- Repository: https://github.com/n-haru0524/one

## Overview

1. **Two-layer structure: core library plus application layer**
   - The repository splits into a reusable robotics core in `one/` and an assembly-focused application stack in `one_assembly/`.
   - `one/` provides general-purpose scene, robot, collision, physics, motion-planning, and visualization primitives.
   - `one_assembly/` builds on top of that core for task-level assembly workflows such as screw operations, worklist execution, and robot-specific assembly planning.

2. **Rendering and scene management are a first-class subsystem**
   - `one/scene/` defines the scene graph, renderable objects, geometry primitives, and collision-shape metadata.
   - `one/viewer/` is the low-level OpenGL/pyglet rendering layer: camera, shaders, framebuffers/device buffers, input, render targets, and world orchestration.
   - The viewer is not just a display shell; it is tightly coupled to the scene model and is used for interactive robotics debugging and animation.

3. **Geometry and mesh handling sit between models and algorithms**
   - `one/geom/` and `one/scene/geometry_loader.py` provide mesh loading, fitting, raycasting, transforms, and surface/shape utilities.
   - These modules feed both visualization and computation-heavy subsystems such as collision detection and grasp planning.
   - STL assets in the repo root and under robot folders are part of this geometry pipeline.

4. **Collision checking has multiple backends with a common interface**
   - `one/collider/` is a dedicated collision subsystem with CPU SIMD, GPU compute-shader, MuJoCo-based, and fallback/TBD implementations.
   - The key architectural boundary is that higher-level planners depend on collision results, not on a specific backend.
   - Data typically flows from scene objects or robot models into collision batches or MuJoCo collision wrappers, then back to planners as feasibility checks or contact points.

5. **MuJoCo is the simulation and native collision backbone**
   - `one/physics/` handles MuJoCo compilation, runtime stepping, contact extraction, naming, and conversion between internal objects and MuJoCo structures.
   - This is the main bridge from the framework’s own scene/robot abstractions to executable simulation.
   - The repository’s architecture intentionally keeps MuJoCo as the single dynamics backend rather than layering in a separate physics engine.

6. **Robot modeling is organized by mechanism type**
   - `one/robots/` contains base kinematics/mechanics abstractions plus concrete families: manipulators, end effectors, humanoids, and mobile robots.
   - Robot implementations include kinematic solvers, URDF loaders, mechanism structures, and model-specific mesh assets.
   - The codebase supports both full robot bodies and modular attachment of end effectors such as grippers and tools.

7. **Kinematics and inverse kinematics are separate from motion planning**
   - `one/robots/base/kine/` provides analytical and numerical IK, kinematic chains, and geometric solvers.
   - These solvers support both robot-specific pose computation and higher-level planners that need feasibility checks or end-effector targeting.
   - This separation keeps pose solving local to robot models while motion planning works in configuration space.

8. **Motion planning is a distinct probabilistic layer**
   - `one/motion/probabilistic/` contains state-space definitions, RRT/RRT-Connect, PRM, planning context, and post-processing.
   - `one/motion/trajectory/` covers trajectory generation and time parameterization once a discrete path has been found.
   - The planners depend on the collision subsystem through state-space providers, which is the main coupling between planning and environment geometry.

9. **Grasp planning is geometry- and collision-driven**
   - `one/grasp/` implements antipodal grasp generation and placement-related logic.
   - It uses surface geometry, raycasting, and collision/contact evaluation to produce feasible grasps.
   - In practice, grasping is a mid-layer capability: it consumes object geometry and produces robot-ready end-effector poses for planning.

10. **`one_assembly/` is the task-execution stack**
   - `one_assembly/assembly_planning.py`, `work.py`, and `worklist.py` define higher-level assembly tasks, sequencing, and work state.
   - `one_assembly/motion_planner/` contains task-specific planners such as approach/depart, pick-place, fold, screw, and hierarchical sequencing.
   - `one_assembly/precise_collision.py` suggests a more specialized collision layer for assembly tolerances than the general-purpose core colliders.

11. **Screw-operation pipeline has its own end-to-end flow**
   - `one_assembly/ScrewOperation/` is a self-contained subsystem with configuration, camera integration, dataset handling, inference, training, correction loops, and session management.
   - It includes bridges for external I/O, data collection, pose CSV generation, and visual/metric evaluation scripts.
   - This looks like a domain-specific ML-assisted correction and execution loop layered on top of the robotics core.

12. **Hardware and external-system integration is isolated behind adapters**
   - `one/communication/` and `one/commu/` contain communication backends with Linux `ctypes` and Windows `.NET` adapters, implying platform-specific device or controller links.
   - `one/stream/websocket_server.py` is a separate real-time streaming boundary, likely used for remote visualization or control.
   - `one_assembly/ros2_bridge.py` indicates a ROS 2 integration point for bringing the framework into a larger robotics stack.

13. **Repository entrypoints are mostly executable examples**
   - The root `test_*.py` files and `nagai/test_*.py` scripts function as demos, integration tests, and scenario-specific validation rather than conventional unit tests.
   - They cover robot visualization, collision backends, kinematics, motion planning, physics simulation, and assembly workflows.
   - Top-level scripts like `main.py`, `game_crane.py`, `mujoco_viewer.py`, and `check_opengl.py` act as focused launchers or diagnostics.

14. **Static web assets provide an alternate UI boundary**
   - `web/` contains a browser-side viewer/control layer with `index.html`, `main.js`, and a custom camera-controls script.
   - This is separate from the pyglet viewer and likely serves lightweight remote interaction or demo playback.
   - The architecture therefore has two UI surfaces: native OpenGL/pyglet for primary interaction and web assets for browser-facing interaction.

Main entry points: [`one/motion`](https://github.com/n-haru0524/one/tree/main/one/motion) (Motion), [`one/collider`](https://github.com/n-haru0524/one/tree/main/one/collider) (Collider), [`one/physics`](https://github.com/n-haru0524/one/tree/main/one/physics) (MuJoCo bridge), [`one/viewer`](https://github.com/n-haru0524/one/tree/main/one/viewer) (Viewer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core robotics"]
  node_scene["Scene"]
  node_geom["Geometry<br/>mesh ops"]
  node_collider["Collider<br/>collision backends"]
  node_physics["MuJoCo bridge<br/>simulation bridge"]
  node_robots["Robots<br/>robot models"]
  node_kine["Kinematics<br/>IK/chain solvers"]
  node_motion["Motion<br/>planning layer"]
  node_grasp["Grasping<br/>grasp planning"]
  node_comm["Comm<br/>device adapters"]
end

subgraph group_assembly["Assembly stack"]
  node_assembly["Assembly<br/>task orchestration"]
  node_asm_planners["Task planners<br/>assembly motion"]
  node_precise_collision["Precise collision<br/>assembly collision"]
  node_screwop["Screw op<br/>screw pipeline"]
end

subgraph group_ui["UI and streaming"]
  node_viewer["Viewer<br/>OpenGL UI"]
  node_stream["Streaming<br/>websocket I/O"]
  node_web["Web UI<br/>browser viewer"]
end

subgraph group_assets["Robot assets"]
  node_robots_assets["Robot assets<br/>mechanism assets"]
  node_asm_robot_assets["Assembly robots<br/>assembly mechanisms"]
end

node_examples["Examples<br/>demos/entrypoints"]

node_scene -->|"loads geometry"| node_geom
node_viewer -->|"renders"| node_scene
node_viewer -->|"shows meshes"| node_geom
node_collider -->|"checks objects"| node_scene
node_collider -->|"uses shapes"| node_geom
node_physics -->|"syncs model"| node_scene
node_physics -->|"simulates"| node_robots
node_robots -->|"solves poses"| node_kine
node_grasp -->|"analyzes surfaces"| node_geom
node_grasp -->|"validates contact"| node_collider
node_motion -->|"feasibility"| node_collider
node_motion -->|"targets poses"| node_kine
node_motion -->|"executes"| node_physics
node_comm -->|"hardware link"| node_physics
node_stream -->|"streams view"| node_viewer
node_web -->|"remote control"| node_stream
node_assembly -->|"orchestrates"| node_motion
node_assembly -->|"binds robots"| node_robots
node_asm_planners -->|"specializes"| node_motion
node_asm_planners -->|"checks tolerance"| node_precise_collision
node_screwop -->|"drives"| node_asm_planners
node_screwop -->|"debugs"| node_viewer
node_examples -.->|"launches"| node_viewer
node_examples -.->|"validates"| node_collider
node_examples -.->|"runs planners"| node_motion
node_examples -.->|"simulates"| node_physics
node_examples -.->|"exercises"| node_assembly
node_robots_assets -->|"define models"| node_robots
node_asm_robot_assets -->|"task assets"| node_assembly

click node_scene "https://github.com/n-haru0524/one/tree/main/one/scene"
click node_viewer "https://github.com/n-haru0524/one/tree/main/one/viewer"
click node_geom "https://github.com/n-haru0524/one/tree/main/one/geom"
click node_collider "https://github.com/n-haru0524/one/tree/main/one/collider"
click node_physics "https://github.com/n-haru0524/one/tree/main/one/physics"
click node_robots "https://github.com/n-haru0524/one/tree/main/one/robots"
click node_kine "https://github.com/n-haru0524/one/tree/main/one/robots/base/kine"
click node_motion "https://github.com/n-haru0524/one/tree/main/one/motion"
click node_grasp "https://github.com/n-haru0524/one/tree/main/one/grasp"
click node_comm "https://github.com/n-haru0524/one/tree/main/one/communication"
click node_stream "https://github.com/n-haru0524/one/tree/main/one/stream"
click node_web "https://github.com/n-haru0524/one/tree/main/web"
click node_assembly "https://github.com/n-haru0524/one/tree/main/one_assembly"
click node_asm_planners "https://github.com/n-haru0524/one/tree/main/one_assembly/motion_planner"
click node_precise_collision "https://github.com/n-haru0524/one/blob/main/one_assembly/precise_collision.py"
click node_screwop "https://github.com/n-haru0524/one/tree/main/one_assembly/ScrewOperation"
click node_robots_assets "https://github.com/n-haru0524/one/tree/main/one/robots/manipulators"
click node_asm_robot_assets "https://github.com/n-haru0524/one/tree/main/one_assembly/robots"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scene,node_geom,node_collider,node_physics,node_robots,node_kine,node_motion,node_grasp,node_comm toneBlue
class node_assembly,node_asm_planners,node_precise_collision,node_screwop toneAmber
class node_viewer,node_stream,node_web toneMint
class node_robots_assets,node_asm_robot_assets toneRose
class node_examples toneNeutral
```

## Components

### Core robotics

Reusable scene, geometry, robot, collision, physics, motion, and visualization layers.

- [Scene](https://github.com/n-haru0524/one/tree/main/one/scene): scene graph · Renderable objects, scene nodes, geometry loading, and collision-shape metadata. · `one/scene`
- [Geometry](https://github.com/n-haru0524/one/tree/main/one/geom): mesh ops · Mesh loading, fitting, raycasting, transforms, surface, and 2D/3D geometry utilities. · `one/geom`
- [Collider](https://github.com/n-haru0524/one/tree/main/one/collider): collision backends · Common collision interface with CPU, GPU, MuJoCo, and fallback implementations. · `one/collider`
- [MuJoCo bridge](https://github.com/n-haru0524/one/tree/main/one/physics): simulation bridge · Compilation, stepping, contact extraction, naming, and conversion to MuJoCo runtime structures. · `one/physics`
- [Robots](https://github.com/n-haru0524/one/tree/main/one/robots): robot models · Base kinematics/mechanics plus concrete manipulators, end effectors, humanoids, and mobile robots. · `one/robots`
- [Kinematics](https://github.com/n-haru0524/one/tree/main/one/robots/base/kine): IK/chain solvers · Analytical and numerical IK, kinematic chains, and geometric solvers. · `one/robots/base/kine`
- [Motion](https://github.com/n-haru0524/one/tree/main/one/motion): planning layer · Probabilistic planning and trajectory generation from paths to timed motion. · `one/motion`
- [Grasping](https://github.com/n-haru0524/one/tree/main/one/grasp): grasp planning · Antipodal grasp generation and placement logic driven by geometry and collision. · `one/grasp`
- [Comm](https://github.com/n-haru0524/one/tree/main/one/communication): device adapters · Platform-specific communication backends for external hardware and controllers. · `one/communication`

### Assembly stack

Task-level planning and execution built on the robotics core.

- [Assembly](https://github.com/n-haru0524/one/tree/main/one_assembly): task orchestration · Work state, sequence planning, and assembly-specific planning utilities. · `one_assembly`
- [Task planners](https://github.com/n-haru0524/one/tree/main/one_assembly/motion_planner): assembly motion · Approach/depart, pick-place, fold, screw, and hierarchical assembly planning. · `one_assembly/motion_planner`
- [Precise collision](https://github.com/n-haru0524/one/blob/main/one_assembly/precise_collision.py): assembly collision · Assembly-focused collision layer for tighter tolerances and task-specific checks. · `one_assembly/precise_collision.py`
- [Screw op](https://github.com/n-haru0524/one/tree/main/one_assembly/ScrewOperation): screw pipeline · Domain-specific pipeline with camera, data, inference, correction, sessions, and evaluation. · `one_assembly/ScrewOperation`

### UI and streaming

Native viewer, web viewer, and realtime streaming boundaries.

- [Viewer](https://github.com/n-haru0524/one/tree/main/one/viewer): OpenGL UI · Camera, shaders, buffers, render targets, input, and world orchestration for interactive visualization. · `one/viewer`
- [Streaming](https://github.com/n-haru0524/one/tree/main/one/stream): websocket I/O · Realtime streaming boundary for remote visualization or control. · `one/stream`
- [Web UI](https://github.com/n-haru0524/one/tree/main/web): browser viewer · Static browser-facing viewer and control surface. · `web`

### Robot assets

Representative robot and geometry asset sets used by the core and assembly stack.

- [Robot assets](https://github.com/n-haru0524/one/tree/main/one/robots/manipulators): mechanism assets · Representative robot and end-effector models plus mesh assets used across the repo. · `one/robots/manipulators`
- [Assembly robots](https://github.com/n-haru0524/one/tree/main/one_assembly/robots): assembly mechanisms · Assembly-specific robot and tool models with meshes for task execution. · `one_assembly/robots`

### Other components

- **Examples**: demos/entrypoints · Executable demos and scenario scripts exercising visualization, collision, planning, and assembly flows.

## Connections

- Scene → Geometry: loads geometry · Scene objects depend on mesh and transform utilities.
- Viewer → Scene: renders · Viewer consumes scene/world state for interactive display.
- Viewer → Geometry: shows meshes · Rendering uses geometry and mesh data.
- Collider → Scene: checks objects · Collision backends operate on scene objects and batches.
- Collider → Geometry: uses shapes · Collision computation relies on mesh and shape representations.
- MuJoCo bridge → Scene: syncs model · MuJoCo bridge converts scene/robot abstractions to runtime structures.
- MuJoCo bridge → Robots: simulates · Robot models are compiled and stepped in MuJoCo.
- Robots → Kinematics: solves poses · Robot models delegate chain and IK solving to kinematics.
- Grasping → Geometry: analyzes surfaces · Grasp generation uses surface geometry and raycasting.
- Grasping → Collider: validates contact · Feasible grasps depend on collision/contact checks.
- Motion → Collider: feasibility · Planners query collision through state-space providers.
- Motion → Kinematics: targets poses · Motion planning consumes kinematic feasibility and end-effector goals.
- Motion → MuJoCo bridge: executes · Planned motion can be validated or run in simulation.
- Comm → MuJoCo bridge: hardware link · Communication adapters connect external systems around the simulator/control boundary.
- Streaming → Viewer: streams view · Websocket streaming can expose viewer state remotely.
- Web UI → Streaming: remote control · Browser UI acts as a separate interaction surface over streaming.
- Assembly → Motion: orchestrates · Assembly workflows build on probabilistic planning and trajectory generation.
- Assembly → Robots: binds robots · Assembly tasks use robot models and tools.
- Task planners → Motion: specializes · Task planners specialize the core motion layer for assembly behaviors.
- Task planners → Precise collision: checks tolerance · Assembly planners use tighter collision logic for task execution.
- Screw op → Task planners: drives · Screw operation pipeline coordinates screw-specific planning and execution.
- Screw op → Viewer: debugs · The pipeline is likely inspected through visual/debug workflows.
- Examples → Viewer: launches · Top-level scripts and test-like demos exercise the viewer.
- Examples → Collider: validates · Examples probe collision backends and geometry interactions.
- Examples → Motion: runs planners · Demo scripts exercise PRM/RRT and time parameterization.
- Examples → MuJoCo bridge: simulates · Examples run MuJoCo-backed robot and object scenarios.
- Examples → Assembly: exercises · Scenario scripts cover assembly workflows and screw operations.
- Robot assets → Robots: define models · Representative robot families and end effectors live as model assets.
- Assembly robots → Assembly: task assets · Assembly-specific robot/tool meshes and mechanism definitions support task execution.
