Simplify repository

README.md

@@ -4,89 +4,53 @@ tags:
   - image-editing
   - lora
   - robotics
-  - hand-editing
-base_model:
-  - meituan-longcat/LongCat-Image-Edit
-  - Shitao/OmniGen-v1
-  - black-forest-labs/FLUX.2-klein-base-4B
-  - stepfun-ai/Step1X-Edit
 ---
 
 # HandEdit LoRA
 
-HandEdit provides parameter-efficient LoRA adapters that specialize four
-open-source image-editing backbones for human-to-robot-hand replacement.
+LoRA checkpoints for replacing human hands with Inspire robot hands while
+preserving the original pose, object interaction, background, lighting, and
+camera view.
 
-We build more than 20K aligned training pairs from the HandEdit data. Each pair
-contains an input image with a real human hand interacting with an object and a
-corresponding target image in which only the hand is replaced by an Inspire
-robotic hand. The training instruction asks the model to preserve the original
-wrist pose, finger configuration, grasp relation, object contact points,
-interaction object, background, lighting, and camera viewpoint as closely as
-possible.
-
-Only LoRA parameters are released; the full base-model weights are not
-redistributed.
+The adapters were trained on 20K+ aligned image-editing pairs.
 
 ## Models
 
-| Adapter | Official base model | Local checkpoint |
+| Model | Base model | Checkpoint |
 | --- | --- | --- |
-| LongCat-Image-Edit | [`meituan-longcat/LongCat-Image-Edit`](https://huggingface.co/meituan-longcat/LongCat-Image-Edit) | `checkpoints/longcat/` |
-| OmniGen-v1 | [`Shitao/OmniGen-v1`](https://huggingface.co/Shitao/OmniGen-v1) | `checkpoints/omnigen/` |
-| FLUX.2 Klein Base 4B | [`black-forest-labs/FLUX.2-klein-base-4B`](https://huggingface.co/black-forest-labs/FLUX.2-klein-base-4B) | `checkpoints/flux2/handedit_flux2_klein4b_lora.safetensors` |
-| Step1X-Edit | [`stepfun-ai/Step1X-Edit`](https://huggingface.co/stepfun-ai/Step1X-Edit) | `checkpoints/step1x/inspire_step1x_r32_a16_res512.safetensors` |
+| LongCat-Image-Edit | `meituan-longcat/LongCat-Image-Edit` | `checkpoints/longcat/` |
+| OmniGen-v1 | `Shitao/OmniGen-v1` | `checkpoints/omnigen/` |
+| FLUX.2 Klein Base 4B | `black-forest-labs/FLUX.2-klein-base-4B` | `checkpoints/flux2/` |
+| Step1X-Edit | `stepfun-ai/Step1X-Edit` | `checkpoints/step1x/` |
 
 ## Download
 
-**[Download all four sanitized LoRA checkpoints](https://huggingface.co/HandEdit/HandEdit-LoRA/resolve/main/checkpoints.zip?download=true)**
-
-Or download and verify them from the command line:
-
 ```bash
-pip install huggingface_hub
-python scripts/download_weights.py
-python scripts/verify_weights.py
+hf download HandEdit/HandEdit-LoRA \
+  --include "checkpoints/**" \
+  --local-dir .
 ```
 
-The published ZIP and individual adapter files are hosted in
-[`HandEdit/HandEdit-LoRA`](https://huggingface.co/HandEdit/HandEdit-LoRA).
-
 ## Inference
 
-Detailed environment setup and commands are in
-[`docs/INFERENCE.md`](docs/INFERENCE.md). The shortest examples are:
+Run from the repository root:
 
 ```bash
-# LongCat-Image-Edit
 python scripts/infer_longcat_lora.py \
-  --input_dir ./examples/input --output_dir ./outputs/longcat
+  --input_dir ./input --output_dir ./output/longcat
 
-# OmniGen-v1
 python scripts/infer_omnigen_lora.py \
-  --input_dir ./examples/input --output_dir ./outputs/omnigen
+  --input_dir ./input --output_dir ./output/omnigen
 
-# FLUX.2 Klein Base 4B
 python scripts/infer_flux2_lora.py \
-  --input_dir ./examples/input --output_dir ./outputs/flux2
+  --input_dir ./input --output_dir ./output/flux2
 
-# Step1X-Edit
 python scripts/infer_step1x_lora.py \
   --repo_dir ./third_party/Step1X-Edit \
   --model_dir ./weights/Step1X-Edit \
-  --input_dir ./examples/input --output_dir ./outputs/step1x \
+  --input_dir ./input --output_dir ./output/step1x \
   --quantized --offload
 ```
 
-## Release hygiene
-
-The public weights are sanitized copies. Training-data identifiers, dataset
-sizes, local paths, author fields, timestamps, session information, and other
-training-process metadata were removed without changing tensor bytes. See
-[`SANITIZATION.md`](SANITIZATION.md) and `weights_manifest.json`.
-
-## Base-model licenses
-
-Users must follow the license and access terms of each official base model.
-This repository does not redistribute the four base models.
-
+Only the LoRA adapters are included. Download the corresponding base models
+from their official repositories.

SANITIZATION.md

@@ -1,14 +0,0 @@
-# Release sanitization
-
-The public checkpoint files are sanitized copies, not the original training
-artifacts.
-
-- Optional SafeTensors metadata was removed from all four adapters.
-- Published SafeTensors headers retain only `{"format": "pt"}`.
-- PEFT JSON files contain only adapter architecture and loading parameters.
-- Dataset identifiers, dataset sizes, local paths, timestamps, author fields,
-  host/session information, and training-process metadata are not published.
-- Tensor names, shapes, data types, offsets, and tensor data bytes were preserved.
-
-`weights_manifest.json` records checksums for the sanitized release files.
-

checkpoints.zip

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:9e89032b37d439205e940821f82735c790a35e5c32b4813ab985fb5ee0fdcad2
-size 621076920

docs/INFERENCE.md

@@ -1,132 +0,0 @@
-# Inference
-
-Run commands from the repository root. The four upstream projects do not
-necessarily share one dependency set, so separate virtual environments are
-recommended.
-
-## 1. Download the HandEdit adapters
-
-Download and extract all four sanitized LoRA adapters:
-
-```bash
-python scripts/download_weights.py
-```
-
-You can verify an existing local copy with:
-
-```bash
-python scripts/verify_weights.py
-```
-
-The base models are not bundled. Download them from their official projects and
-follow the corresponding licenses and access requirements.
-
-## 2. LongCat-Image-Edit
-
-Install the shared dependencies:
-
-```bash
-pip install -r requirements.txt
-```
-
-Run batch inference:
-
-```bash
-python scripts/infer_longcat_lora.py \
-  --input_dir ./examples/input \
-  --output_dir ./outputs/longcat \
-  --skip_existing
-```
-
-The default base model is `meituan-longcat/LongCat-Image-Edit`. Use `--base`
-to point to a local model directory, and add `--local_files_only` for an
-offline cache.
-
-## 3. OmniGen-v1
-
-Install the official OmniGen repository in its own environment:
-
-```bash
-git clone https://github.com/VectorSpaceLab/OmniGen.git third_party/OmniGen
-pip install -e third_party/OmniGen
-pip install peft pillow
-```
-
-Run:
-
-```bash
-python scripts/infer_omnigen_lora.py \
-  --input_dir ./examples/input \
-  --output_dir ./outputs/omnigen \
-  --offload_model \
-  --skip_existing
-```
-
-The default base model is `Shitao/OmniGen-v1`.
-
-## 4. FLUX.2 Klein Base 4B
-
-Install the shared dependencies:
-
-```bash
-pip install -r requirements.txt
-```
-
-Run:
-
-```bash
-python scripts/infer_flux2_lora.py \
-  --input_dir ./examples/input \
-  --output_dir ./outputs/flux2 \
-  --skip_existing
-```
-
-The default base model is
-`black-forest-labs/FLUX.2-klein-base-4B`. The script uses model CPU offload by
-default; select `--offload sequential` for lower VRAM or `--offload none` for
-maximum speed on a sufficiently large GPU.
-
-## 5. Step1X-Edit
-
-Clone and install the official repository in its own environment:
-
-```bash
-git clone https://github.com/stepfun-ai/Step1X-Edit.git third_party/Step1X-Edit
-pip install -r third_party/Step1X-Edit/requirements.txt
-```
-
-Prepare the official base-model directory expected by Step1X:
-
-```text
-weights/Step1X-Edit/
-├── Qwen2.5-VL-7B-Instruct/
-├── step1x-edit-i1258.safetensors
-└── vae.safetensors
-```
-
-Run:
-
-```bash
-python scripts/infer_step1x_lora.py \
-  --repo_dir ./third_party/Step1X-Edit \
-  --model_dir ./weights/Step1X-Edit \
-  --input_dir ./examples/input \
-  --output_dir ./outputs/step1x \
-  --version v1.0 \
-  --quantized \
-  --offload \
-  --skip_existing
-```
-
-## Shared edit instruction
-
-The scripts use the following default instruction:
-
-> Edit only the human hand region. Replace the human hand with a realistic
-> Inspire robotic hand with correct robotic finger structure and joints.
-> Preserve the original wrist pose, palm orientation, finger articulation,
-> grasp geometry, and contact points with the object. Keep the object,
-> background, lighting, camera viewpoint, and all non-hand regions unchanged.
-
-Override it with `--prompt` when needed.
-

requirements.txt

@@ -1,14 +0,0 @@
-# Shared runtime for LongCat-Image-Edit and FLUX.2 Klein.
-# OmniGen and Step1X additionally require their official repositories;
-# see docs/INFERENCE.md.
-accelerate>=1.2
-huggingface_hub>=0.28
-numpy>=1.24
-peft>=0.18.0
-pillow>=10.0
-safetensors>=0.4
-torch>=2.5
-torchvision>=0.20
-transformers>=4.57
-git+https://github.com/huggingface/diffusers.git
-

scripts/download_weights.py

@@ -1,91 +0,0 @@
-#!/usr/bin/env python3
-"""Download and safely extract the published HandEdit LoRA archive."""
-
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import shutil
-import zipfile
-from pathlib import Path
-
-from huggingface_hub import hf_hub_download
-
-DEFAULT_REPO_ID = "HandEdit/HandEdit-LoRA"
-ARCHIVE_NAME = "checkpoints.zip"
-
-
-def sha256(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as handle:
-        for chunk in iter(lambda: handle.read(8 * 1024 * 1024), b""):
-            digest.update(chunk)
-    return digest.hexdigest()
-
-
-def safe_extract(archive: Path, destination: Path) -> None:
-    root = destination.resolve()
-    with zipfile.ZipFile(archive) as bundle:
-        for member in bundle.infolist():
-            target = (root / member.filename).resolve()
-            if target != root and root not in target.parents:
-                raise RuntimeError(f"Unsafe archive member: {member.filename}")
-        bundle.extractall(root)
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(
-        description="Download the sanitized HandEdit LoRA checkpoints."
-    )
-    parser.add_argument("--repo-id", default=DEFAULT_REPO_ID)
-    parser.add_argument(
-        "--output-dir",
-        type=Path,
-        default=Path("."),
-        help="Repository root where checkpoints/ will be extracted.",
-    )
-    parser.add_argument(
-        "--keep-archive",
-        action="store_true",
-        help="Keep checkpoints.zip after successful extraction.",
-    )
-    args = parser.parse_args()
-
-    output_dir = args.output_dir.expanduser().resolve()
-    output_dir.mkdir(parents=True, exist_ok=True)
-    archive = Path(
-        hf_hub_download(
-            repo_id=args.repo_id,
-            filename=ARCHIVE_NAME,
-            repo_type="model",
-            local_dir=output_dir,
-        )
-    )
-
-    manifest_path = Path(
-        hf_hub_download(
-            repo_id=args.repo_id,
-            filename="weights_manifest.json",
-            repo_type="model",
-            local_dir=output_dir,
-        )
-    )
-    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
-    expected = manifest["archive"]["sha256"]
-    actual = sha256(archive)
-    if actual != expected:
-        raise RuntimeError(
-            f"Archive checksum mismatch: expected {expected}, received {actual}"
-        )
-
-    safe_extract(archive, output_dir)
-    print(f"[OK] Extracted sanitized weights to: {output_dir / 'checkpoints'}")
-    if not args.keep_archive:
-        archive.unlink()
-        print(f"[OK] Removed downloaded archive: {archive}")
-
-
-if __name__ == "__main__":
-    main()
-

scripts/verify_weights.py

@@ -1,56 +0,0 @@
-#!/usr/bin/env python3
-"""Verify local sanitized LoRA files against weights_manifest.json."""
-
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-from pathlib import Path
-
-
-def sha256(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as handle:
-        for chunk in iter(lambda: handle.read(8 * 1024 * 1024), b""):
-            digest.update(chunk)
-    return digest.hexdigest()
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Verify HandEdit LoRA checkpoints.")
-    parser.add_argument(
-        "--root",
-        type=Path,
-        default=Path("."),
-        help="Repository root containing weights_manifest.json and checkpoints/.",
-    )
-    args = parser.parse_args()
-
-    root = args.root.expanduser().resolve()
-    manifest = json.loads(
-        (root / "weights_manifest.json").read_text(encoding="utf-8")
-    )
-    failures = []
-    for adapter in manifest["adapters"].values():
-        for item in adapter["files"]:
-            path = root / item["path"]
-            if not path.is_file():
-                failures.append(f"missing: {item['path']}")
-                continue
-            if path.stat().st_size != item["size_bytes"]:
-                failures.append(f"size mismatch: {item['path']}")
-                continue
-            if sha256(path) != item["sha256"]:
-                failures.append(f"SHA-256 mismatch: {item['path']}")
-                continue
-            print(f"[OK] {item['path']}")
-
-    if failures:
-        raise SystemExit("\n".join(failures))
-    print("[DONE] All sanitized LoRA files passed verification.")
-
-
-if __name__ == "__main__":
-    main()
-

weights_manifest.json

@@ -1,61 +0,0 @@
-{
-  "repo_id": "HandEdit/HandEdit-LoRA",
-  "release_type": "sanitized_lora_adapters",
-  "archive": {
-    "path": "checkpoints.zip",
-    "size_bytes": 621076920,
-    "sha256": "9e89032b37d439205e940821f82735c790a35e5c32b4813ab985fb5ee0fdcad2"
-  },
-  "adapters": {
-    "longcat": {
-      "base_model": "meituan-longcat/LongCat-Image-Edit",
-      "files": [
-        {
-          "path": "checkpoints/longcat/adapter_config.json",
-          "size_bytes": 530,
-          "sha256": "9ec4fbd1d7c3c3d9c6eef9cbee0cadf0c1fb1ce4874fd7e0252d666bd1eb8e9a"
-        },
-        {
-          "path": "checkpoints/longcat/adapter_model.safetensors",
-          "size_bytes": 94421944,
-          "sha256": "2391face660c6e5dd5439553d96f89059c8bfa5160af89778455cf9bf8568a5e"
-        }
-      ]
-    },
-    "omnigen": {
-      "base_model": "Shitao/OmniGen-v1",
-      "files": [
-        {
-          "path": "checkpoints/omnigen/adapter_config.json",
-          "size_bytes": 307,
-          "sha256": "7a285bafa03c63d6414a098f76b737fa3fb143f7257a6edf0ad0442cc412cbcc"
-        },
-        {
-          "path": "checkpoints/omnigen/adapter_model.safetensors",
-          "size_bytes": 18891496,
-          "sha256": "6863295d2829c25eeed85eb175d5d21ee5867b2536023124d9f1cd2dfce9b971"
-        }
-      ]
-    },
-    "flux2": {
-      "base_model": "black-forest-labs/FLUX.2-klein-base-4B",
-      "files": [
-        {
-          "path": "checkpoints/flux2/handedit_flux2_klein4b_lora.safetensors",
-          "size_bytes": 369643968,
-          "sha256": "11a9d65f8b53a1f1de08d5bcf02c181ebc122ae79661367bdad3b5fddeac591a"
-        }
-      ]
-    },
-    "step1x": {
-      "base_model": "stepfun-ai/Step1X-Edit",
-      "files": [
-        {
-          "path": "checkpoints/step1x/inspire_step1x_r32_a16_res512.safetensors",
-          "size_bytes": 306426744,
-          "sha256": "e32ef656e023b0cc503ab0a24f645a3e99ba32ce8cae3dbd0eba221b988c1156"
-        }
-      ]
-    }
-  }
-}