ParkerLabel README

The project's README from github.com/Parker-Lyu/ParkerLabel. As one markdown file: README.md.

English | 简体中文 | 繁體中文 | 日本語 | 한국어

ParkerLabel icon

ParkerLabel

Runs entirely on the CPU—no GPU required.

A lightweight, polished AI-assisted interactive annotation tool for object detection and instance segmentation.

Each interactive mask-decoder inference takes approximately 20 ms on Apple M5 Pro and Intel Core i9-14900KF CPUs.

GitHub Releases macOS arm64 build target Windows x64 build target GPL-3.0-only license

ParkerLabel interactive annotation demo

🎬 Project Overview

Watch the ParkerLabel introduction on YouTube   Watch the ParkerLabel introduction on Bilibili

Run

Use a portable release

  1. Download a published application package for your platform from GitHub Releases or Baiduyun (extraction code: md7r). Releases named models-* contain ONNX models, not application packages.

  2. On macOS and Windows, you need to move the entire extracted ParkerLabel folder to a writable location before opening it.

  3. The macOS package is ad-hoc signed but is not notarized by Apple. The first launch may therefore be blocked by macOS. After attempting to open the app once, open System Settings → Privacy & Security, scroll to the security section, and choose Open Anyway.

  4. On Windows, Microsoft Defender SmartScreen may show Windows protected your PC when you first launch the app. Click More info, then Run anyway.

macOS first-launch warning: click Done macOS Privacy and Security: click Open Anyway
Windows SmartScreen: click More info Windows SmartScreen: click Run anyway

These warnings alone do not mean ParkerLabel is malicious. Portable releases are built with GitHub Actions; you can review the build workflow and build instructions.

Run from source

Install a Conda distribution if you do not already have one. Miniforge is recommended, but other Conda distributions also work. Clone the project from GitHub or Gitee:

git clone https://github.com/Parker-Lyu/ParkerLabel.git

Or:

git clone https://gitee.com/Parker-Lyu/ParkerLabel.git

Then create a Python 3.11 environment, install the dependencies, and start ParkerLabel:

cd ParkerLabel
conda create -n parker-label -c conda-forge python=3.11 -y
conda activate parker-label
python -m pip install -r requirements.txt
python main.py

ParkerLabel automatically verifies and downloads missing ONNX models into pretrain/.

Overview

ParkerLabel supports 中文（简体）, 中文（繁體）, English, 日本語, 한국어, Deutsch, Français, Italiano, and Español. Use Settings → Interface Language to change the interface language and Settings → Tooltips to control contextual hints.

Use Settings → Keyboard Shortcuts to view, change, clear, or restore key bindings. AI, Manual, and Inspect modes use Q, W, and E by default. In AI mode, positive and negative clicks guide MobileSAM to generate a mask for the current target. The image toolbar uses S to toggle AI prompt points in the overlay view and C to toggle quality checks. Saved bindings take effect immediately and persist across launches.

Category configurations

ParkerLabel includes a read-only configuration containing the 80 standard COCO object-detection categories. Users can create an empty category configuration or copy any existing configuration—including the built-in COCO configuration—to create a new version. Saved configurations are immutable; further changes are made by copying a configuration into another version. User-created configurations are stored in the selected configs/categories/ directory.

Each annotation is bound to a category configuration by its UUID and SHA-256 digest. If another configuration is active, ParkerLabel offers to switch to the required one. The annotation opens read-only if that configuration is unavailable, fails integrity checks, or the user declines the switch.

Portable settings, including the startup category selection, are stored in configs/settings.ini. The application log is configs/app.log; it is cleared on each launch and limited to two 1 MB files while the app runs.

Annotation files

Each source image uses three neighboring artifact files:

The per-image JSON uses COCO annotation fields but is not a complete COCO dataset file. A complete COCO dataset export requires top-level images, annotations, and categories arrays in one dataset JSON.

JSON fields

Regenerate ONNX models

Dependencies: Install torch and torchvision using the PyTorch instructions for your platform, then run python -m pip install timm onnx onnxruntime==1.29.0. Verified versions: torch 2.13.0, torchvision 0.28.0, timm 1.0.19, onnx 1.22.0, and onnxruntime 1.29.0.

Checkpoint: Create pretrain/, then download the official MobileSAM mobile_sam.pt to pretrain/mobile_sam.pt. It is the only weight needed for both exports; no separate TinyViT or SAM checkpoint is required.

Export: From the repository root, run:

python -m mobile_sam.export_mobilesam_encoder --checkpoint pretrain/mobile_sam.pt --output pretrain/encoder.onnx
python -m mobile_sam.export_mobilesam_decoder --checkpoint pretrain/mobile_sam.pt --model-type vit_t --output pretrain/decoder.onnx

These commands regenerate the ONNX models for development. At startup, ParkerLabel checks their sizes and SHA-256 hashes against model-bundle.json and replaces mismatched files with the published models. Custom exports require a matching model manifest. mobile_sam.pt and the export dependencies are not needed at runtime. Model files in pretrain/ are excluded from Git.

Licenses

ParkerLabel's original code, including mobile_sam/export_mobilesam_encoder.py, is licensed under GPL-3.0-only.

The third-party code in mobile_sam/ retains its own licenses: MobileSAM and Segment Anything use Apache License 2.0, and the TinyViT code carries a Microsoft MIT notice. See mobile_sam/LICENSE, mobile_sam/TINYVIT_LICENSE, and mobile_sam/THIRD_PARTY.md for the license texts and attribution.

The GUI uses PyQt5 and Qt under their own licenses. Exact final-package notices, corresponding-source instructions, and Qt replacement instructions are maintained in third_party_licenses/. Model source and export provenance are recorded in docs/model-provenance.md, and the release audit procedure is in docs/release-licenses.md.

Acknowledgements

ParkerLabel's AI-assisted segmentation workflow is built on the work of:

We thank the authors and contributors of both projects for making their work publicly available.

ParkerLabel (Parker-Lyu/ParkerLabel)

Searching Database…

109 ·GitHub
ParkerLabel
What is this?ParkerLabel is a lightweight, AI-assisted interactive annotation tool for object detection and instance segmentation that uses MobileSAM to generate masks from click prompts.
Is this a desktop app or a library I'd import into code?It's a standalone desktop GUI application with a PyQt5 interface, distributed as portable release packages, not a library.
How do I get it running?Either download a portable application package for your OS from GitHub Releases (or Baiduyun), or clone the repo, create a Python 3.11 Conda environment, install dependencies, and start it from source.
Any install pitfalls on macOS or Windows?On macOS the package is ad-hoc signed but not notarized, so the first launch is blocked until you allow it via Privacy & Security settings; on Windows, SmartScreen may warn and require clicking 'Run anyway'.
Which operating systems does it support?Portable packages are published for macOS and Windows, and it can also be run from source on any platform with Conda (e.g. Linux).
Does my data or images get sent anywhere?No, everything runs locally on CPU; annotation data is stored as local .npy, .json, and .mask.png files next to each source image.
How does the AI-assisted labeling actually work?In AI mode you give positive and negative clicks on an image, and MobileSAM generates an instance mask from those prompts in real time (about 20 ms per inference on modern CPUs).
What category sets can I use for labeling?ParkerLabel ships with a read-only built-in configuration of the 80 standard COCO categories, and you can create new category configurations or copy existing ones, each tracked by UUID and SHA-256 digest.
What format are the annotation files saved in?Each image gets a JSON file with per-instance category, bounding box, area, and uncompressed COCO RLE segmentation, plus a cached image embedding (.npy) and a color mask preview (.mask.png); the JSON uses COCO-style fields but isn't a full COCO dataset export.
Which languages does the interface support?ParkerLabel's UI supports Simplified and Traditional Chinese, English, Japanese, Korean, German, French, Italian, and Spanish, switchable in Settings.
What are similar projects?X-AnyLabeling, label-studio, cvat, labelImg, supervision, albumentations, ingetrazo, labelme
Which topics is it in?bounding-boxes, image-annotation, data-labeling, cpu-inference, annotation, image-segmentation, qt, object-detection, onnx, offline, computer-vision, pytorch
Creator
Parker-Lyu
Size
7.3 MB
Stars
109
Updated
CommitOct 09Releasev1.0.0Oct 06
Age
1mo
Commits · 90 Days