kmk 0.1.0__tar.gz

kmk-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.3
+Name: kmk
+Version: 0.1.0
+Summary: Keypoint-based multi-fingered hand kinematics and configuration tools.
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: scipy>=1.13.0
+Requires-Dist: torch>=2.3.0
+Requires-Dist: tyro>=0.8.12
+Requires-Dist: viser>=1.0.24
+Requires-Dist: yourdfpy>=0.0.60
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/kh11kim/kmk.git
+Project-URL: Repository, https://github.com/kh11kim/kmk.git
+Description-Content-Type: text/markdown
+
+# kmk
+
+`kmk` is a utility repo for authoring and consuming keypoint-based multi-fingered hand kinematics data.
+
+It has two main jobs:
+
+- a staged GUI wizard that builds a hand config YAML
+- runtime loaders and torch kinematics utilities that read that YAML
+
+## What This Repo Provides
+
+- `gripper_config_wizard`
+  - staged authoring flow for:
+    - global hand config
+    - per-link contact anchors
+    - grasp templates
+    - final preview/confirmation
+- `HandInfo`
+  - read-only runtime wrapper around the authored YAML
+- `PointedHandInfo`
+  - `HandInfo` plus precomputed surface/contact point samples
+- `HandKinematics`
+  - torch forward kinematics for batched joint vectors and link-local point sets
+
+## User Workflow
+
+1. Prepare a gripper root directory containing at least a URDF.
+2. Run the wizard.
+3. Fill the global stage.
+   - palm pose
+   - palm points delta
+   - global `q_open`
+   - extra collision ignore pairs
+4. Fill the keypoint stage.
+   - one contact anchor per link
+   - point, radius, tags
+5. Fill the grasp template stage.
+   - `q_open`, `q_close`
+   - `grasp_target_point`
+   - active contact anchors
+6. Check the final preview and press `Confirmed`.
+7. Use the saved YAML through `HandInfo`, `PointedHandInfo`, or `HandKinematics`.
+
+## Install
+
+```bash
+uv sync
+```
+
+## Wizard
+
+Create a new config:
+
+```bash
+uv run gripper_config_wizard --gripper-root /path/to/gripper_root
+```
+
+Edit an existing config:
+
+```bash
+uv run gripper_config_wizard \
+  --gripper-root /path/to/gripper_root \
+  --from-config existing.yaml
+```
+
+Notes:
+
+- `--from-config` relative paths are resolved from `gripper_root`.
+- `urdf_path` and `xml_path` stored in YAML are typically relative paths.
+
+## Visualization
+
+Inspect a saved config and sampled points:
+
+```bash
+uv run python visualize/pointed_hand_info.py --config-path /path/to/hand.yaml
+```
+
+Inspect batched torch kinematics:
+
+```bash
+uv run python visualize/hand_kinematics_batch.py --config-path /path/to/hand.yaml
+```
+
+## Runtime API
+
+### `HandInfo`
+
+```python
+from kmk import HandInfo
+
+hand = HandInfo.from_config("hand.yaml")
+q_open = hand.get_q_open()
+q_close = hand.get_q_close("finger4_shallow")
+palm_pose = hand.get_palm_pose()
+anchor = hand.get_contact_anchor_by_link("right_1thumb_distal")
+anchors = hand.get_contact_anchor_by_template("finger4_shallow")
+target = hand.get_grasp_target_point("finger4_shallow")
+```
+
+Main API:
+
+- `HandInfo.from_config(config_path)`
+- `joint_order`
+- `template_names`
+- `contact_anchor_links`
+- `get_q_open(template="global")`
+- `get_q_close(template_name)`
+- `get_palm_pose()`
+- `get_contact_anchor_by_link(link_name)`
+- `get_contact_anchor_by_tag(includes=(), excludes=())`
+- `get_contact_anchor_by_template(template_name)`
+- `get_grasp_target_point(template_name)`
+
+### `PointedHandInfo`
+
+```python
+from kmk import PointedHandInfo
+
+hand = PointedHandInfo.from_config("hand.yaml", seed=0)
+surface_points = hand.surface_points
+contact_points = hand.get_contact_points("finger4_shallow")
+keypoints = hand.get_keypoints("finger4_shallow", palm_aligned_points=True)
+```
+
+Main additions:
+
+- `surface_points`
+- `contact_points`
+- `get_contact_points(template_name=None)`
+- `get_keypoints(template_name=None, palm_aligned_points=True, palm_points_delta=...)`
+
+### `HandKinematics`
+
+```python
+import torch
+from kmk import HandInfo, HandKinematics
+
+hand = HandInfo.from_config("hand.yaml")
+kin = HandKinematics(hand).to(device="cpu")
+
+q = torch.zeros(16, len(hand.joint_order))
+fk = kin.forward_kinematics(q)
+world_points = kin.transform_link_points(
+    q,
+    {"right_1thumb_distal": torch.tensor([[0.0, 0.0, 0.02]])},
+)
+```
+
+Main API:
+
+- `HandKinematics(hand_info_or_config_path)`
+- `joint_order`
+- `link_names`
+- `dof`
+- `forward_kinematics(q)`
+- `transform_link_points(q, points_by_link)`
+- `get_palm_pose(batch_shape=None)`
+
+## Config Schema
+
+The detailed spec lives in [`SPEC.md`](/Users/polde/ws/kmk/SPEC.md).

kmk-0.1.0/README.md

@@ -0,0 +1,162 @@
+# kmk
+
+`kmk` is a utility repo for authoring and consuming keypoint-based multi-fingered hand kinematics data.
+
+It has two main jobs:
+
+- a staged GUI wizard that builds a hand config YAML
+- runtime loaders and torch kinematics utilities that read that YAML
+
+## What This Repo Provides
+
+- `gripper_config_wizard`
+  - staged authoring flow for:
+    - global hand config
+    - per-link contact anchors
+    - grasp templates
+    - final preview/confirmation
+- `HandInfo`
+  - read-only runtime wrapper around the authored YAML
+- `PointedHandInfo`
+  - `HandInfo` plus precomputed surface/contact point samples
+- `HandKinematics`
+  - torch forward kinematics for batched joint vectors and link-local point sets
+
+## User Workflow
+
+1. Prepare a gripper root directory containing at least a URDF.
+2. Run the wizard.
+3. Fill the global stage.
+   - palm pose
+   - palm points delta
+   - global `q_open`
+   - extra collision ignore pairs
+4. Fill the keypoint stage.
+   - one contact anchor per link
+   - point, radius, tags
+5. Fill the grasp template stage.
+   - `q_open`, `q_close`
+   - `grasp_target_point`
+   - active contact anchors
+6. Check the final preview and press `Confirmed`.
+7. Use the saved YAML through `HandInfo`, `PointedHandInfo`, or `HandKinematics`.
+
+## Install
+
+```bash
+uv sync
+```
+
+## Wizard
+
+Create a new config:
+
+```bash
+uv run gripper_config_wizard --gripper-root /path/to/gripper_root
+```
+
+Edit an existing config:
+
+```bash
+uv run gripper_config_wizard \
+  --gripper-root /path/to/gripper_root \
+  --from-config existing.yaml
+```
+
+Notes:
+
+- `--from-config` relative paths are resolved from `gripper_root`.
+- `urdf_path` and `xml_path` stored in YAML are typically relative paths.
+
+## Visualization
+
+Inspect a saved config and sampled points:
+
+```bash
+uv run python visualize/pointed_hand_info.py --config-path /path/to/hand.yaml
+```
+
+Inspect batched torch kinematics:
+
+```bash
+uv run python visualize/hand_kinematics_batch.py --config-path /path/to/hand.yaml
+```
+
+## Runtime API
+
+### `HandInfo`
+
+```python
+from kmk import HandInfo
+
+hand = HandInfo.from_config("hand.yaml")
+q_open = hand.get_q_open()
+q_close = hand.get_q_close("finger4_shallow")
+palm_pose = hand.get_palm_pose()
+anchor = hand.get_contact_anchor_by_link("right_1thumb_distal")
+anchors = hand.get_contact_anchor_by_template("finger4_shallow")
+target = hand.get_grasp_target_point("finger4_shallow")
+```
+
+Main API:
+
+- `HandInfo.from_config(config_path)`
+- `joint_order`
+- `template_names`
+- `contact_anchor_links`
+- `get_q_open(template="global")`
+- `get_q_close(template_name)`
+- `get_palm_pose()`
+- `get_contact_anchor_by_link(link_name)`
+- `get_contact_anchor_by_tag(includes=(), excludes=())`
+- `get_contact_anchor_by_template(template_name)`
+- `get_grasp_target_point(template_name)`
+
+### `PointedHandInfo`
+
+```python
+from kmk import PointedHandInfo
+
+hand = PointedHandInfo.from_config("hand.yaml", seed=0)
+surface_points = hand.surface_points
+contact_points = hand.get_contact_points("finger4_shallow")
+keypoints = hand.get_keypoints("finger4_shallow", palm_aligned_points=True)
+```
+
+Main additions:
+
+- `surface_points`
+- `contact_points`
+- `get_contact_points(template_name=None)`
+- `get_keypoints(template_name=None, palm_aligned_points=True, palm_points_delta=...)`
+
+### `HandKinematics`
+
+```python
+import torch
+from kmk import HandInfo, HandKinematics
+
+hand = HandInfo.from_config("hand.yaml")
+kin = HandKinematics(hand).to(device="cpu")
+
+q = torch.zeros(16, len(hand.joint_order))
+fk = kin.forward_kinematics(q)
+world_points = kin.transform_link_points(
+    q,
+    {"right_1thumb_distal": torch.tensor([[0.0, 0.0, 0.02]])},
+)
+```
+
+Main API:
+
+- `HandKinematics(hand_info_or_config_path)`
+- `joint_order`
+- `link_names`
+- `dof`
+- `forward_kinematics(q)`
+- `transform_link_points(q, points_by_link)`
+- `get_palm_pose(batch_shape=None)`
+
+## Config Schema
+
+The detailed spec lives in [`SPEC.md`](/Users/polde/ws/kmk/SPEC.md).

kmk-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "kmk"
+version = "0.1.0"
+description = "Keypoint-based multi-fingered hand kinematics and configuration tools."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=2.0.0",
+    "pyyaml>=6.0.1",
+    "scipy>=1.13.0",
+    "torch>=2.3.0",
+    "tyro>=0.8.12",
+    "viser>=1.0.24",
+    "yourdfpy>=0.0.60",
+]
+
+[project.urls]
+Homepage = "https://github.com/kh11kim/kmk.git"
+Repository = "https://github.com/kh11kim/kmk.git"
+
+[dependency-groups]
+dev = [
+    "playwright>=1.58.0",
+    "pytest>=8.2.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.6,<0.10.0"]
+build-backend = "uv_build"
+
+[project.scripts]
+gripper_config_wizard = "kmk.wizard.cli:main"

kmk-0.1.0/src/kmk/__init__.py

@@ -0,0 +1,7 @@
+"""kmk package."""
+
+from .config.model import GripperConfig
+from .hand_info import HandInfo, PointedHandInfo
+from .kinematics import HandKinematics
+
+__all__ = ["GripperConfig", "HandInfo", "PointedHandInfo", "HandKinematics"]

kmk-0.1.0/src/kmk/config/__init__.py

@@ -0,0 +1,12 @@
+"""Config helpers."""
+
+from .model import GripperConfig
+from .parse import ParsedUrdfNames, ParsedXmlNames, parse_urdf_names, parse_xml_names
+
+__all__ = [
+    "GripperConfig",
+    "ParsedUrdfNames",
+    "ParsedXmlNames",
+    "parse_urdf_names",
+    "parse_xml_names",
+]