Add files using upload-large-folder tool

README.md

@@ -0,0 +1,92 @@
+---
+library_name: peft
+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.
+
+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.
+
+## Models
+
+| Adapter | Official base model | Local 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` |
+
+## 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
+```
+
+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:
+
+```bash
+# LongCat-Image-Edit
+python scripts/infer_longcat_lora.py \
+  --input_dir ./examples/input --output_dir ./outputs/longcat
+
+# OmniGen-v1
+python scripts/infer_omnigen_lora.py \
+  --input_dir ./examples/input --output_dir ./outputs/omnigen
+
+# FLUX.2 Klein Base 4B
+python scripts/infer_flux2_lora.py \
+  --input_dir ./examples/input --output_dir ./outputs/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 \
+  --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.
+

SANITIZATION.md

@@ -0,0 +1,14 @@
+# 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

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

checkpoints/flux2/handedit_flux2_klein4b_lora.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:11a9d65f8b53a1f1de08d5bcf02c181ebc122ae79661367bdad3b5fddeac591a
+size 369643968

checkpoints/longcat/adapter_config.json

@@ -0,0 +1,27 @@
+{
+  "bias": "none",
+  "fan_in_fan_out": false,
+  "inference_mode": true,
+  "init_lora_weights": "gaussian",
+  "lora_alpha": 8,
+  "lora_dropout": 0.0,
+  "peft_type": "LORA",
+  "r": 32,
+  "target_modules": [
+    "attn.to_add_out",
+    "attn.to_q",
+    "attn.add_v_proj",
+    "attn.to_v",
+    "attn.add_k_proj",
+    "attn.add_q_proj",
+    "ff_context.net.2",
+    "ff_context.net.0.proj",
+    "attn.to_k",
+    "ff.net.0.proj",
+    "attn.to_out.0",
+    "ff.net.2"
+  ],
+  "task_type": null,
+  "use_dora": false,
+  "use_rslora": false
+}

checkpoints/longcat/adapter_model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2391face660c6e5dd5439553d96f89059c8bfa5160af89778455cf9bf8568a5e
+size 94421944

checkpoints/omnigen/adapter_config.json

@@ -0,0 +1,17 @@
+{
+  "bias": "none",
+  "fan_in_fan_out": false,
+  "inference_mode": true,
+  "init_lora_weights": "gaussian",
+  "lora_alpha": 16,
+  "lora_dropout": 0.0,
+  "peft_type": "LORA",
+  "r": 16,
+  "target_modules": [
+    "o_proj",
+    "qkv_proj"
+  ],
+  "task_type": null,
+  "use_dora": false,
+  "use_rslora": false
+}

checkpoints/omnigen/adapter_model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6863295d2829c25eeed85eb175d5d21ee5867b2536023124d9f1cd2dfce9b971
+size 18891496

checkpoints/step1x/inspire_step1x_r32_a16_res512.safetensors

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

docs/INFERENCE.md

@@ -0,0 +1,132 @@
+# 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

@@ -0,0 +1,14 @@
+# 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

@@ -0,0 +1,91 @@
+#!/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/infer_flux2_lora.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Batch image editing with FLUX.2 Klein and a Diffusers-compatible LoRA file."""
+
+import argparse
+from pathlib import Path
+
+import torch
+from PIL import Image
+from diffusers import Flux2KleinPipeline
+
+IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".webp", ".bmp"}
+DEFAULT_BASE = "black-forest-labs/FLUX.2-klein-base-4B"
+DEFAULT_PROMPT = (
+    "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. "
+    "The robot hand must be kinematically feasible and physically plausible, without penetrating "
+    "the object. Keep the object pose, shape, texture, background, lighting, camera viewpoint, "
+    "and all non-hand regions unchanged."
+)
+
+
+def list_images(input_dir: Path, recursive: bool):
+    iterator = input_dir.rglob("*") if recursive else input_dir.iterdir()
+    return sorted(
+        path for path in iterator
+        if path.is_file() and path.suffix.lower() in IMAGE_EXTS
+    )
+
+
+def load_lora(pipe, lora_path: str, scale: float):
+    path = Path(lora_path).expanduser()
+    adapter_name = "handedit"
+    if path.is_file():
+        pipe.load_lora_weights(
+            str(path.parent),
+            weight_name=path.name,
+            adapter_name=adapter_name,
+        )
+    else:
+        pipe.load_lora_weights(str(path), adapter_name=adapter_name)
+    pipe.set_adapters(adapter_name, adapter_weights=scale)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Batch inference for FLUX.2 Klein with a LoRA checkpoint."
+    )
+    parser.add_argument(
+        "--base",
+        default=DEFAULT_BASE,
+        help=f"FLUX.2 Klein model directory or model ID (default: {DEFAULT_BASE}).",
+    )
+    parser.add_argument(
+        "--lora",
+        default="./checkpoints/flux2/handedit_flux2_klein4b_lora.safetensors",
+        help="LoRA .safetensors file or adapter directory.",
+    )
+    parser.add_argument("--input_dir", required=True)
+    parser.add_argument("--output_dir", required=True)
+    parser.add_argument("--prompt", default=DEFAULT_PROMPT)
+    parser.add_argument("--steps", type=int, default=50)
+    parser.add_argument("--guidance_scale", type=float, default=4.0)
+    parser.add_argument("--lora_scale", type=float, default=1.0)
+    parser.add_argument("--seed", type=int, default=43)
+    parser.add_argument("--seed_mode", choices=["fixed", "increment"], default="fixed")
+    parser.add_argument("--offload", choices=["model", "sequential", "none"], default="model")
+    parser.add_argument("--local_files_only", action="store_true")
+    parser.add_argument("--suffix", default="")
+    parser.add_argument("--recursive", action="store_true")
+    parser.add_argument("--skip_existing", action="store_true")
+    args = parser.parse_args()
+
+    if not torch.cuda.is_available():
+        raise RuntimeError("CUDA is required for practical FLUX.2 inference.")
+
+    input_root = Path(args.input_dir).expanduser().resolve()
+    output_root = Path(args.output_dir).expanduser().resolve()
+    if not input_root.is_dir():
+        raise FileNotFoundError(f"Input directory not found: {input_root}")
+    output_root.mkdir(parents=True, exist_ok=True)
+
+    paths = list_images(input_root, args.recursive)
+    if not paths:
+        raise RuntimeError(f"No images found under: {input_root}")
+
+    print("[1/3] Loading FLUX.2 Klein...")
+    pipe = Flux2KleinPipeline.from_pretrained(
+        args.base,
+        torch_dtype=torch.bfloat16,
+        local_files_only=args.local_files_only,
+    )
+
+    print("[2/3] Loading LoRA adapter...")
+    load_lora(pipe, args.lora, args.lora_scale)
+
+    if args.offload == "model":
+        pipe.enable_model_cpu_offload()
+    elif args.offload == "sequential":
+        pipe.enable_sequential_cpu_offload()
+    else:
+        pipe.to("cuda")
+
+    print(f"[3/3] Processing {len(paths)} images...")
+    current_seed = args.seed
+    for index, input_path in enumerate(paths, start=1):
+        relative = input_path.relative_to(input_root)
+        output_path = output_root / relative.with_name(relative.stem + args.suffix + ".png")
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if args.skip_existing and output_path.exists():
+            print(f"[{index}/{len(paths)}] SKIP {output_path}")
+        else:
+            image = Image.open(input_path).convert("RGB")
+            generator = torch.Generator("cpu").manual_seed(current_seed)
+            result = pipe(
+                prompt=args.prompt,
+                image=image,
+                num_inference_steps=args.steps,
+                guidance_scale=args.guidance_scale,
+                generator=generator,
+            ).images[0]
+            result.save(output_path)
+            print(f"[{index}/{len(paths)}] OK {input_path.name} -> {output_path}")
+
+        if args.seed_mode == "increment":
+            current_seed += 1
+
+    print(f"[DONE] Results saved under: {output_root}")
+
+
+if __name__ == "__main__":
+    main()

scripts/infer_longcat_lora.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Batch image editing with LongCat-Image-Edit and a PEFT LoRA adapter."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import torch
+from diffusers import LongCatImageEditPipeline
+from peft import PeftModel
+from PIL import Image
+
+IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".webp", ".bmp"}
+DEFAULT_BASE = "meituan-longcat/LongCat-Image-Edit"
+DEFAULT_PROMPT = (
+    "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. "
+    "The robot hand must be kinematically feasible and physically plausible, without penetrating "
+    "the object. Keep the object pose, shape, texture, background, lighting, camera viewpoint, "
+    "and all non-hand regions unchanged."
+)
+
+
+def list_images(input_dir: Path, recursive: bool) -> list[Path]:
+    iterator = input_dir.rglob("*") if recursive else input_dir.iterdir()
+    return sorted(
+        path
+        for path in iterator
+        if path.is_file() and path.suffix.lower() in IMAGE_EXTS
+    )
+
+
+def apply_lora_scale(model: torch.nn.Module, scale: float) -> int:
+    """Multiply every active PEFT LoRA layer scale by ``scale``."""
+    if scale == 1.0:
+        return 0
+    changed = 0
+    for module in model.modules():
+        scaling = getattr(module, "scaling", None)
+        if isinstance(scaling, dict):
+            for adapter_name in list(scaling):
+                scaling[adapter_name] *= scale
+                changed += 1
+    return changed
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Batch inference for LongCat-Image-Edit with the HandEdit LoRA."
+    )
+    parser.add_argument(
+        "--base",
+        default=DEFAULT_BASE,
+        help=f"Base model directory or model ID (default: {DEFAULT_BASE}).",
+    )
+    parser.add_argument(
+        "--lora",
+        default="./checkpoints/longcat",
+        help="PEFT LoRA directory (default: ./checkpoints/longcat).",
+    )
+    parser.add_argument("--input_dir", required=True)
+    parser.add_argument("--output_dir", required=True)
+    parser.add_argument("--prompt", default=DEFAULT_PROMPT)
+    parser.add_argument("--negative_prompt", default="")
+    parser.add_argument("--guidance_scale", type=float, default=4.5)
+    parser.add_argument("--steps", type=int, default=50)
+    parser.add_argument("--seed", type=int, default=43)
+    parser.add_argument(
+        "--seed_mode", choices=["fixed", "increment"], default="fixed"
+    )
+    parser.add_argument("--lora_scale", type=float, default=1.0)
+    parser.add_argument(
+        "--offload", choices=["model", "sequential", "none"], default="model"
+    )
+    parser.add_argument("--local_files_only", action="store_true")
+    parser.add_argument("--suffix", default="")
+    parser.add_argument("--recursive", action="store_true")
+    parser.add_argument("--skip_existing", action="store_true")
+    args = parser.parse_args()
+
+    if not torch.cuda.is_available():
+        raise RuntimeError("CUDA is required for practical LongCat inference.")
+    if args.steps < 2:
+        raise ValueError("--steps must be at least 2")
+    if args.guidance_scale < 0:
+        raise ValueError("--guidance_scale must be non-negative")
+
+    input_root = Path(args.input_dir).expanduser().resolve()
+    output_root = Path(args.output_dir).expanduser().resolve()
+    lora_root = Path(args.lora).expanduser().resolve()
+    if not input_root.is_dir():
+        raise FileNotFoundError(f"Input directory not found: {input_root}")
+    if not lora_root.is_dir():
+        raise FileNotFoundError(f"LoRA directory not found: {lora_root}")
+
+    paths = list_images(input_root, args.recursive)
+    if not paths:
+        raise RuntimeError(f"No images found under: {input_root}")
+    output_root.mkdir(parents=True, exist_ok=True)
+
+    print("[1/3] Loading LongCat-Image-Edit...")
+    pipe = LongCatImageEditPipeline.from_pretrained(
+        args.base,
+        torch_dtype=torch.bfloat16,
+        local_files_only=args.local_files_only,
+    )
+
+    print("[2/3] Loading HandEdit LoRA...")
+    pipe.transformer = PeftModel.from_pretrained(
+        pipe.transformer,
+        str(lora_root),
+        is_trainable=False,
+    )
+    changed = apply_lora_scale(pipe.transformer, args.lora_scale)
+    if args.lora_scale != 1.0:
+        print(
+            f"[INFO] LoRA scale={args.lora_scale}; "
+            f"adjusted {changed} active LoRA layers."
+        )
+
+    if args.offload == "model":
+        pipe.enable_model_cpu_offload()
+    elif args.offload == "sequential":
+        pipe.enable_sequential_cpu_offload()
+    else:
+        pipe.to("cuda")
+
+    print(f"[3/3] Processing {len(paths)} images...")
+    current_seed = args.seed
+    for index, input_path in enumerate(paths, start=1):
+        relative = input_path.relative_to(input_root)
+        output_path = output_root / relative.with_name(
+            relative.stem + args.suffix + ".png"
+        )
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if args.skip_existing and output_path.exists():
+            print(f"[{index}/{len(paths)}] SKIP {output_path}")
+        else:
+            with Image.open(input_path) as source:
+                image = source.convert("RGB")
+            generator = torch.Generator("cpu").manual_seed(current_seed)
+            result = pipe(
+                image,
+                args.prompt,
+                negative_prompt=args.negative_prompt,
+                guidance_scale=args.guidance_scale,
+                num_inference_steps=args.steps,
+                num_images_per_prompt=1,
+                generator=generator,
+            ).images[0]
+            result.save(output_path)
+            print(f"[{index}/{len(paths)}] OK {input_path.name} -> {output_path}")
+
+        if args.seed_mode == "increment":
+            current_seed += 1
+
+    print(f"[DONE] Results saved under: {output_root}")
+
+
+if __name__ == "__main__":
+    main()

scripts/infer_omnigen_lora.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""Batch image editing with OmniGen-v1 and a fine-tuned LoRA checkpoint."""
+
+import argparse
+from pathlib import Path
+
+from PIL import Image
+from OmniGen import OmniGenPipeline
+
+IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".webp", ".bmp"}
+DEFAULT_BASE = "Shitao/OmniGen-v1"
+DEFAULT_PROMPT = (
+    "<img><|image_1|></img> 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. The robot hand must be kinematically feasible and "
+    "physically plausible, without penetrating the object. Keep the object pose, shape, texture, "
+    "background, lighting, camera viewpoint, and all non-hand regions unchanged."
+)
+
+
+def list_images(input_dir: Path, recursive: bool):
+    iterator = input_dir.rglob("*") if recursive else input_dir.iterdir()
+    return sorted(
+        path for path in iterator
+        if path.is_file() and path.suffix.lower() in IMAGE_EXTS
+    )
+
+
+def target_size(image_path: Path, max_size: int):
+    with Image.open(image_path) as image:
+        width, height = image.size
+    scale = min(1.0, max_size / max(width, height))
+    width = max(16, round(width * scale / 16) * 16)
+    height = max(16, round(height * scale / 16) * 16)
+    return width, height
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Batch inference for OmniGen-v1 with a LoRA checkpoint."
+    )
+    parser.add_argument(
+        "--base",
+        default=DEFAULT_BASE,
+        help=f"OmniGen-v1 model directory or model ID (default: {DEFAULT_BASE}).",
+    )
+    parser.add_argument(
+        "--lora",
+        default="./checkpoints/omnigen",
+        help="LoRA checkpoint directory (default: ./checkpoints/omnigen).",
+    )
+    parser.add_argument("--input_dir", required=True)
+    parser.add_argument("--output_dir", required=True)
+    parser.add_argument("--prompt", default=DEFAULT_PROMPT)
+    parser.add_argument("--steps", type=int, default=50)
+    parser.add_argument("--guidance_scale", type=float, default=2.5)
+    parser.add_argument("--img_guidance_scale", type=float, default=1.6)
+    parser.add_argument("--max_size", type=int, default=512)
+    parser.add_argument("--seed", type=int, default=43)
+    parser.add_argument("--seed_mode", choices=["fixed", "increment"], default="fixed")
+    parser.add_argument("--suffix", default="")
+    parser.add_argument("--recursive", action="store_true")
+    parser.add_argument("--skip_existing", action="store_true")
+    parser.add_argument("--offload_model", action="store_true")
+    args = parser.parse_args()
+
+    input_root = Path(args.input_dir).expanduser().resolve()
+    output_root = Path(args.output_dir).expanduser().resolve()
+    if not input_root.is_dir():
+        raise FileNotFoundError(f"Input directory not found: {input_root}")
+    output_root.mkdir(parents=True, exist_ok=True)
+
+    paths = list_images(input_root, args.recursive)
+    if not paths:
+        raise RuntimeError(f"No images found under: {input_root}")
+
+    print("[1/3] Loading OmniGen-v1...")
+    pipe = OmniGenPipeline.from_pretrained(args.base)
+
+    print("[2/3] Merging LoRA checkpoint...")
+    pipe.merge_lora(args.lora)
+
+    print(f"[3/3] Processing {len(paths)} images...")
+    current_seed = args.seed
+    for index, input_path in enumerate(paths, start=1):
+        relative = input_path.relative_to(input_root)
+        output_path = output_root / relative.with_name(relative.stem + args.suffix + ".png")
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if args.skip_existing and output_path.exists():
+            print(f"[{index}/{len(paths)}] SKIP {output_path}")
+        else:
+            width, height = target_size(input_path, args.max_size)
+            images = pipe(
+                prompt=args.prompt,
+                input_images=[str(input_path)],
+                height=height,
+                width=width,
+                num_inference_steps=args.steps,
+                guidance_scale=args.guidance_scale,
+                img_guidance_scale=args.img_guidance_scale,
+                max_input_image_size=args.max_size,
+                separate_cfg_infer=True,
+                use_kv_cache=True,
+                offload_kv_cache=True,
+                offload_model=args.offload_model,
+                use_input_image_size_as_output=False,
+                seed=current_seed,
+            )
+            images[0].save(output_path)
+            print(f"[{index}/{len(paths)}] OK {input_path.name} -> {output_path}")
+
+        if args.seed_mode == "increment":
+            current_seed += 1
+
+    print(f"[DONE] Results saved under: {output_root}")
+
+
+if __name__ == "__main__":
+    main()

scripts/infer_step1x_lora.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""Batch image editing with the official Step1X-Edit code and a LoRA file."""
+
+import argparse
+import importlib.util
+import sys
+from pathlib import Path
+
+import torch
+from PIL import Image
+
+IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".webp", ".bmp"}
+DEFAULT_PROMPT = (
+    "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. "
+    "The robot hand must be kinematically feasible and physically plausible, without penetrating "
+    "the object. Keep the object pose, shape, texture, background, lighting, camera viewpoint, "
+    "and all non-hand regions unchanged."
+)
+
+
+def list_images(input_dir: Path, recursive: bool):
+    iterator = input_dir.rglob("*") if recursive else input_dir.iterdir()
+    return sorted(
+        path for path in iterator
+        if path.is_file() and path.suffix.lower() in IMAGE_EXTS
+    )
+
+
+def import_official_inference(repo_dir: Path):
+    inference_file = repo_dir / "inference.py"
+    if not inference_file.is_file():
+        raise FileNotFoundError(f"Official inference.py not found: {inference_file}")
+
+    sys.path.insert(0, str(repo_dir))
+    spec = importlib.util.spec_from_file_location("step1x_official_inference", inference_file)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Unable to import: {inference_file}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Batch inference for Step1X-Edit v1.0/v1.1 with a LoRA checkpoint."
+    )
+    parser.add_argument("--repo_dir", required=True, help="Official Step1X-Edit repository directory.")
+    parser.add_argument(
+        "--model_dir",
+        required=True,
+        help="Directory containing the DiT checkpoint, VAE, and Qwen2.5-VL directory.",
+    )
+    parser.add_argument(
+        "--lora",
+        default="./checkpoints/step1x/inspire_step1x_r32_a16_res512.safetensors",
+        help="Step1X LoRA .safetensors file.",
+    )
+    parser.add_argument("--input_dir", required=True)
+    parser.add_argument("--output_dir", required=True)
+    parser.add_argument("--prompt", default=DEFAULT_PROMPT)
+    parser.add_argument("--version", choices=["v1.0", "v1.1"], default="v1.0")
+    parser.add_argument("--steps", type=int, default=28)
+    parser.add_argument("--cfg_guidance", type=float, default=6.0)
+    parser.add_argument("--size_level", type=int, default=512)
+    parser.add_argument("--seed", type=int, default=42)
+    parser.add_argument("--seed_mode", choices=["fixed", "increment"], default="fixed")
+    parser.add_argument("--quantized", action="store_true")
+    parser.add_argument("--offload", action="store_true")
+    parser.add_argument("--suffix", default="")
+    parser.add_argument("--recursive", action="store_true")
+    parser.add_argument("--skip_existing", action="store_true")
+    args = parser.parse_args()
+
+    if not torch.cuda.is_available():
+        raise RuntimeError("CUDA is required for practical Step1X inference.")
+
+    repo_dir = Path(args.repo_dir).expanduser().resolve()
+    model_dir = Path(args.model_dir).expanduser().resolve()
+    input_root = Path(args.input_dir).expanduser().resolve()
+    output_root = Path(args.output_dir).expanduser().resolve()
+    lora_path = Path(args.lora).expanduser().resolve()
+
+    if not input_root.is_dir():
+        raise FileNotFoundError(f"Input directory not found: {input_root}")
+    if not lora_path.is_file():
+        raise FileNotFoundError(f"LoRA file not found: {lora_path}")
+
+    ckpt_name = (
+        "step1x-edit-i1258.safetensors"
+        if args.version == "v1.0"
+        else "step1x-edit-v1p1-official.safetensors"
+    )
+    required = [
+        model_dir / ckpt_name,
+        model_dir / "vae.safetensors",
+        model_dir / "Qwen2.5-VL-7B-Instruct",
+    ]
+    for path in required:
+        if not path.exists():
+            raise FileNotFoundError(f"Required Step1X component not found: {path}")
+
+    output_root.mkdir(parents=True, exist_ok=True)
+    paths = list_images(input_root, args.recursive)
+    if not paths:
+        raise RuntimeError(f"No images found under: {input_root}")
+
+    official = import_official_inference(repo_dir)
+
+    print("[1/2] Loading Step1X-Edit and LoRA...")
+    generator = official.ImageGenerator(
+        ae_path=str(model_dir / "vae.safetensors"),
+        dit_path=str(model_dir / ckpt_name),
+        qwen2vl_model_path=str(model_dir / "Qwen2.5-VL-7B-Instruct"),
+        max_length=640,
+        quantized=args.quantized,
+        offload=args.offload,
+        lora=str(lora_path),
+        mode="flash",
+        version=args.version,
+    )
+
+    print(f"[2/2] Processing {len(paths)} images...")
+    current_seed = args.seed
+    for index, input_path in enumerate(paths, start=1):
+        relative = input_path.relative_to(input_root)
+        output_path = output_root / relative.with_name(relative.stem + args.suffix + ".png")
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if args.skip_existing and output_path.exists():
+            print(f"[{index}/{len(paths)}] SKIP {output_path}")
+        else:
+            ref_image = Image.open(input_path).convert("RGB")
+            result = generator.generate_image(
+                prompt=args.prompt,
+                negative_prompt="",
+                ref_images=ref_image,
+                num_steps=args.steps,
+                cfg_guidance=args.cfg_guidance,
+                seed=current_seed,
+                num_samples=1,
+                show_progress=True,
+                size_level=args.size_level,
+            )[0]
+            result.save(output_path)
+            print(f"[{index}/{len(paths)}] OK {input_path.name} -> {output_path}")
+
+        if args.seed_mode == "increment":
+            current_seed += 1
+
+    print(f"[DONE] Results saved under: {output_root}")
+
+
+if __name__ == "__main__":
+    main()

scripts/verify_weights.py

@@ -0,0 +1,56 @@
+#!/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

@@ -0,0 +1,61 @@
+{
+  "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"
+        }
+      ]
+    }
+  }
+}