feat: local setup + docs

Justfile

@@ -0,0 +1,31 @@
+set shell := ["bash", "-lc"]
+
+env := "matanyone2-cu132"
+py := "/home/zero/.conda/envs/matanyone2-cu132/bin/python"
+
+default:
+	@just --list
+
+video INPUT MASK:
+	{{py}} inference_matanyone2.py -i "{{INPUT}}" -m "{{MASK}}"
+
+video-save INPUT MASK OUT="results" WARMUP="10" ERODE="10" DILATE="10" MAX_SIZE="-1" SUFFIX="":
+	{{py}} inference_matanyone2.py \
+		-i "{{INPUT}}" \
+		-m "{{MASK}}" \
+		-o "{{OUT}}" \
+		-w "{{WARMUP}}" \
+		-e "{{ERODE}}" \
+		-d "{{DILATE}}" \
+		--max_size "{{MAX_SIZE}}" \
+		--suffix "{{SUFFIX}}" \
+		--save_image
+
+demo:
+	cd hugging_face && {{py}} app.py
+
+gradio:
+	cd hugging_face && {{py}} app.py
+
+help:
+	@just --list

USAGE.md

@@ -0,0 +1,108 @@
+# MatAnyone2 Usage
+
+## Environment
+
+Activate the CUDA env:
+
+```bash
+conda activate matanyone2-cu132
+```
+
+If the `matanyone2` command is not on your PATH, run it through the env Python:
+
+```bash
+/home/zero/.conda/envs/matanyone2-cu132/bin/python -m matanyone2.cli --help
+```
+
+## Input Format
+
+MatAnyone2 takes:
+
+1. A video file such as `.mp4`, `.mov`, or `.avi`, or a folder of extracted frames
+2. A first-frame segmentation mask image
+
+The mask should match the first frame of the input.
+
+## Basic Commands
+
+Process a folder of frames:
+
+```bash
+matanyone2 -i inputs/video/test-sample1 -m inputs/mask/test-sample1.png
+```
+
+Process a video file:
+
+```bash
+matanyone2 -i inputs/video/test-sample2.mp4 -m inputs/mask/test-sample2.png
+```
+
+Use the Python entrypoint directly:
+
+```bash
+python inference_matanyone2.py -i inputs/video/test-sample2.mp4 -m inputs/mask/test-sample2.png
+```
+
+## Output
+
+The default output directory is `results/`.
+
+You will get:
+
+- `*_fgr.mp4` for the foreground composite
+- `*_pha.mp4` for the alpha matte video
+
+If `--save-image` is enabled, per-frame PNGs are also written under:
+
+```text
+results/<video_name>/fgr/
+results/<video_name>/pha/
+```
+
+## Common Settings
+
+```bash
+matanyone2 \
+  -i inputs/video/test-sample2.mp4 \
+  -m inputs/mask/test-sample2.png \
+  -o results/ \
+  -c pretrained_models/matanyone2.pth \
+  -w 10 \
+  -e 10 \
+  -d 10 \
+  --max-size 1080 \
+  --save-image
+```
+
+Flags:
+
+- `-o, --output-path`: where results are written
+- `-c, --ckpt-path`: model checkpoint path
+- `-w, --warmup`: number of warmup frames before saving output
+- `-e, --erode-kernel`: erosion kernel size for the mask
+- `-d, --dilate-kernel`: dilation kernel size for the mask
+- `--suffix`: appended to the output name
+- `--save-image`: also save per-frame PNGs
+- `--max-size`: downsample when the smaller side exceeds this value
+
+## Practical Notes
+
+- The repo will auto-download the checkpoint the first time it runs if `pretrained_models/matanyone2.pth` is missing.
+- This is not a single-image matting tool. A still image needs to be treated as a one-frame video/folder input.
+- For your GPU, use the `matanyone2-cu132` environment.
+
+## Local Demo
+
+To launch the Gradio app:
+
+```bash
+cd hugging_face
+python app.py
+```
+
+If you are missing demo dependencies, install them with:
+
+```bash
+conda activate matanyone2-cu132
+python -m pip install -r hugging_face/requirements.txt
+```

hugging_face/app.py

@@ -1088,4 +1088,4 @@ with gr.Blocks(theme=gr.themes.Monochrome(), css=my_custom_css) as demo:
     gr.Markdown(article)
 
 demo.queue()
-demo.launch(debug=True, share=True)
+demo.launch(debug=True, share=False)

scripts/setup_conda_cuda.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ENV_NAME="${1:-matanyone2-cu132}"
+
+if ! conda env list | awk '{print $1}' | grep -qx "${ENV_NAME}"; then
+  conda create -n "${ENV_NAME}" python=3.10 pip -y --override-channels -c conda-forge
+fi
+
+conda install -n "${ENV_NAME}" pip -y --override-channels -c conda-forge
+
+conda run -n "${ENV_NAME}" python -m pip install --upgrade pip
+conda run -n "${ENV_NAME}" python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cu132
+conda run -n "${ENV_NAME}" python -m pip install -e .
+conda run -n "${ENV_NAME}" python -m pip install -r hugging_face/requirements.txt
+
+mkdir -p pretrained_models
+curl -L https://github.com/pq-yang/MatAnyone2/releases/download/v1.0.0/matanyone2.pth -o pretrained_models/matanyone2.pth
+
+echo "Setup complete for ${ENV_NAME}"