mmdet 계열 검증 86계열 — 디코더·조립기·하네스

CMakeLists.txt

@@ -136,13 +136,11 @@ if(VISP_CI)
     endforeach()
   endif()
 endif()
-# ggml 기본 텐서명 한도 64자는 state_dict 키를 그대로 gguf 텐서명으로 쓰는 모델에 부족하다
-# (mmdet HourglassNet: 68자). 넘으면 로드가 `tensor name is too long: 65 >= 64` 로 거부한다.
-# ★ **ggml 자체 컴파일에도 닿아야 한다** — `ggml_tensor.name[GGML_MAX_NAME]` 이 구조체
-#   레이아웃이라 라이브러리와 헤더의 값이 다르면 ABI 가 갈린다. 그래서 여기(서브디렉터리
-#   추가 **전**)와 `visp/ml.h` 양쪽에 둔다. ml.h 쪽은 CMake 를 안 쓰는 소비자(손수 짠 g++)용.
-#   upstream ggml.h 는 `#ifndef` 가드라 이 정의가 우선한다 — llama 포크 수정 불필요.
-add_compile_definitions(GGML_MAX_NAME=128)
+# 텐서명 한도는 ggml 기본값(64) 을 그대로 쓴다. 그보다 긴 `state_dict` 키는 컴파일러가
+# 줄인다(g2c `shared/compile/tensor_names.py`).
+# 예전엔 여기서 128 로 올렸는데 그건 미루기였다 — 더 깊은 모델이면 또 넘고, **링크되는
+# 모든 소비자가 같은 값을 써야** 해서 손으로 짠 g++ 한 줄만 빠져도 `ggml_tensor` 크기가
+# 갈린다(`char name[GGML_MAX_NAME]` 이 구조체 레이아웃이다).
 
 add_subdirectory(depend/llama/ggml)
 set(BUILD_SHARED_LIBS ${BUILD_SHARED_LIBS_SAVED})

README.md

@@ -10,6 +10,10 @@ Computer Vision ML inference in C++
 
 Based on [ggml](https://github.com/ggml-org/ggml) similar to the [llama.cpp](https://github.com/ggml-org/llama.cpp) project.
 
+New here? [**Getting started**](docs/getting-started.md) walks through a first run in five minutes.
+
+**Docs:** [Getting started](docs/getting-started.md) · [Overview](docs/overview.md) · [Command line](docs/using-the-cli.md) · [Library API](docs/using-the-library.md) · [Implementing a model](docs/model-implementation-guide.md) · [MMDetection models](docs/mmdet-detectors.md)
+
 ### Features
 
 | Model                                    | Task                     | Backends    |
@@ -20,6 +24,8 @@ Based on [ggml](https://github.com/ggml-org/ggml) similar to the [llama.cpp](htt
 | [**MI-GAN**](#mi-gan)                    | Inpainting               | CPU, Vulkan |
 | [**ESRGAN**](#real-esrgan)               | Super-resolution         | CPU, Vulkan |
 | [**YOLOv9t**](#yolov9t)                  | Object detection         | CPU         |
+| [**MMDetection** models](docs/mmdet-detectors.md) | Object detection, segmentation, tracking | CPU |
+| [**Compiled PyTorch models**](docs/mmdet-detectors.md#models-whose-head-survives-tracing) | Any traceable `nn.Module` — ultralytics YOLO, torchvision · full guide in the compiler checkout, `docs/vision-cpp-mmdet-guide-en.md` | CPU |
 | [_Implement a model [**Guide**]_](docs/model-implementation-guide.md) | | |
 
 **Backbones:** SWIN (v1), DINO (v2), TinyViT
@@ -123,7 +129,7 @@ vision-cli migan -m MIGAN-512-places2-F16.gguf -i image.png mask.png -o output.p
 [Model download](https://huggingface.co/Acly/Real-ESRGAN-GGUF) | [Paper (arXiv)](https://arxiv.org/abs/2107.10833) | [Repository (GitHub)](https://github.com/xinntao/Real-ESRGAN) | License: BSD-3-Clause
 
 ```sh
-vision-cli esrgan -m ESRGAN-4x-foolhardy_Remacri-F16.gguf -i input.png -o output.png
+vision-cli esrgan -m RealESRGAN-x4plus_anime-6B-F16.gguf -i input.png -o output.png
 ```
 
 #### YOLOv9t

docs/getting-started.md

@@ -0,0 +1,101 @@
+# Getting Started
+
+In this tutorial you will cut an object out of a photo using vision.cpp. It takes about five
+minutes and needs nothing but the release package, one model file and one image — no build, no
+Python, no conversion.
+
+At the end you will have this:
+
+| | |
+| :--- | :--- |
+| `mask.png` | a black-and-white mask of the object |
+| `object.png` | the original photo with the background dimmed away |
+
+## Step 1 — Get the executable
+
+Download a [release package](https://github.com/Acly/vision.cpp/releases) and extract it. You
+will find `vision-cli` in the `bin` folder.
+
+Check that it runs:
+
+```sh
+vision-cli --help
+```
+
+You should see a list of commands: `sam`, `birefnet`, `depthany`, `migan`, `esrgan`.
+
+> If you would rather build from source, follow [Building](../README.md#building) first, then
+> come back here. `vision-cli` ends up in `build/bin`.
+
+## Step 2 — Get a model and an image
+
+The executable contains the network structure, but not the weights. Download them:
+
+```sh
+curl -L -O https://huggingface.co/Acly/BiRefNet-GGUF/resolve/main/BiRefNet-lite-F16.gguf
+```
+
+This is BiRefNet, a model that separates a subject from its background. The file is a
+[GGUF](https://github.com/ggml-org/ggml/blob/master/docs/gguf.md) — the weights and nothing else.
+
+For the input, use any photo with a clear subject. If you cloned the repository, there is one
+at `docs/media/input.jpg`. Put it next to the model file and call it `input.jpg`.
+
+## Step 3 — Run it
+
+```sh
+vision-cli birefnet -m BiRefNet-lite-F16.gguf -i input.jpg -o mask.png --composite object.png
+```
+
+The output tells you what it is doing:
+
+```
+Initializing backend... done (1.1 ms)
+- device: CPU - Intel(R) Core(TM) i3-14100
+Loading model weights from 'BiRefNet-lite-F16.gguf'... done (151.3 ms)
+- float type: f16
+- tensor layout: cwhn
+- model image size: 1024
+- inference image size: 1024x1024
+- flash attention: off
+Running inference... complete (5372.6 ms)
+-> mask saved to mask.png
+-> image composited and saved to object.png
+```
+
+Inference takes a few seconds on a desktop CPU. Loading the weights takes a fraction of a
+second — that number is the point of the project, and it is the same on any machine.
+
+## Step 4 — Look at the result
+
+Open `object.png`. The subject is untouched and the background has faded away.
+
+`mask.png` is what the model actually produced: white where the subject is, black elsewhere.
+Everything in `object.png` was computed from it.
+
+That is the whole loop. An executable that already knows the network, a `.gguf` that carries
+the weights, an image in, a result out.
+
+## Try one more
+
+The same executable runs the other built-in models. Only the command and the weights change:
+
+```sh
+curl -L -O https://huggingface.co/Acly/Real-ESRGAN-GGUF/resolve/main/RealESRGAN-x4plus_anime-6B-F16.gguf
+
+vision-cli esrgan -m RealESRGAN-x4plus_anime-6B-F16.gguf -i input.jpg -o upscaled.png
+```
+
+This one upscales the image four times. It works on tiles and takes noticeably longer — you will
+see it count them off.
+
+## Where to go next
+
+- [Overview](overview.md) — what the library is and why weights and structure are separate.
+- [Using the command line](using-the-cli.md) — every option, every built-in model.
+- [Using the library](using-the-library.md) — the same models from your own code.
+- [README](../README.md#features) — the other built-in models, and what each one does.
+- [Model implementation guide](model-implementation-guide.md) — when the model you want is not
+  in the list, and you want to add it.
+- [MMDetection detectors](mmdet-detectors.md) — running detectors whose structure is generated
+  rather than hand-written.