How alberthli/frogger works
Project type and purpose
• FRoGGeR is a Python-based computational library/tool for fast, robust grasp generation on robotic hands (Allegro, Barrett, FR3). It is *not* a full-stack web app, but a domain-specific tool that provides an API, CLI scripts, data assets, and example drivers to synthesize grasps via nonlinear optimization.
File structure
• Top-level directories:
• data/ : YCB object meshes, collision meshes, and pickled experimental results
• frogger/ : core Python package (modules: objects, robots, sampling, solvers, baselines, metrics, sdfs, utils)
• models/ : URDF/SDF robot descriptions & meshes for Allegro hand, Barrett hand, FR3, FR3+Zed2i
• examples/ : Python scripts demonstrating API usage
• scripts/ : timing.py CLI driver
• environment.yml, pyproject.toml: dependency management
• Key external config: Drake (via pydrake), numba, jax, MOSEK integration (optional), conda.
README for additional insights
• The README outlines the three inputs: robot model, object description, initial-guess sampler.
• It references Drake solvers, numba for JIT compilation, and describes how modules mesh.
a. Main components:
1) Client layer (Examples & Scripts)
2) FRoGGeR core API modules:
• Objects (MeshObjectConfig, SDF objects)
• Robots (URDF/SDF parsers & model builders: AlgrModelConfig, Barrett, FR3)
• Samplers (HeuristicAlgrICSampler, custom IC Samplers)
• Solvers (FroggerConfig wrapping nonlinear solver)
• Utilities (timeout, viz_config)
• Baselines & Metrics (optional fallback solvers, f-closure metrics)
3) Data assets:
• data/ directory of object meshes & collision meshes
• models/ directory of robot description files & meshes
• pickled experiment outputs (for benchmarking/comparison)
4) Third-party compute layer:
• Drake (pydrake) for dynamics, collision checking, optimization backends (SNOPT/MOSEK)
• numba (JIT) & jax (if SDF analytic objects)
5) Environment & Build:
• conda environment (environment.yml)
• pip editable install (pyproject.toml)
b. Relationships & interactions:
• Examples/scripts → invoke FRoGGeR API →
• FRoGGeR core modules request meshes and robot descriptions →
• Load object meshes from data/ and robot SDF/URDF from models/ →
• Build Drake MultibodyPlant & SceneGraph →
• Sampler generates initial guess →
• Solver (via Drake MathematicalProgram) performs optimization →
• Results returned (joint angles q_star) →
• Viz utils display the result; pickled for benchmarking.
c. Architectural patterns / design principles:
• Modular package structure: one module per concern (objects, robots, solvers).
• Clear separation of data assets vs. code vs. examples.
• Plugin-style extensibility: custom samplers or object definitions.
• Single-file robot description ensures encapsulation for Drake parser.
d. Relevant technologies:
• Python 3.x, pip, conda
• Drake (pydrake) for simulation and optimization
• numba for JIT-accelerated sampling code
• jax (optional) for analytic SDF objects
• MOSEK integration via Drake license
Elements
• Components labeled clearly (Examples, Objects module, Robots module…)
• from examples/scripts to API modules
• from API modules to data assets and to compute backends
• from compute backends back to API and then to UI
Final advice
• Be exhaustive: capture all core modules even if they seem minor.
• Keep it at one screen-width: group modules into logical clusters.