How n-haru0524/one works
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: motion Motion · collider Collider · physics MuJoCo bridge · viewer Viewer
Components 19
Core robotics
Reusable scene, geometry, robot, collision, physics, motion, and visualization layers.
- Scene · Renderable objects, scene nodes, geometry loading, and collision-shape metadata.
one/scene - Geometry · Mesh loading, fitting, raycasting, transforms, surface, and 2D/3D geometry utilities.
one/geom - Collider · Common collision interface with CPU, GPU, MuJoCo, and fallback implementations.
one/collider - MuJoCo bridge · Compilation, stepping, contact extraction, naming, and conversion to MuJoCo runtime structures.
one/physics - Robots · Base kinematics/mechanics plus concrete manipulators, end effectors, humanoids, and mobile robots.
one/robots - Kinematics · Analytical and numerical IK, kinematic chains, and geometric solvers.
one/robots/base/kine - Motion · Probabilistic planning and trajectory generation from paths to timed motion.
one/motion - Grasping · Antipodal grasp generation and placement logic driven by geometry and collision.
one/grasp - Comm · Platform-specific communication backends for external hardware and controllers.
one/communication
Assembly stack
Task-level planning and execution built on the robotics core.
- Assembly · Work state, sequence planning, and assembly-specific planning utilities.
one_assembly - Task planners · Approach/depart, pick-place, fold, screw, and hierarchical assembly planning.
one_assembly/motion_planner - Precise collision · Assembly-focused collision layer for tighter tolerances and task-specific checks.
one_assembly/precise_collision.py - Screw op · 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.
Robot assets
Representative robot and geometry asset sets used by the core and assembly stack.
- Robot assets · Representative robot and end-effector models plus mesh assets used across the repo.
one/robots/manipulators - Assembly robots · Assembly-specific robot and tool models with meshes for task execution.
one_assembly/robots
Other components
- Examples · Executable demos and scenario scripts exercising visualization, collision, planning, and assembly flows.
Connections 29
- 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.