annoviz 0.1.0__tar.gz

annoviz-0.1.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: annoviz
+Version: 0.1.0
+Summary: Local YOLO annotation viewer and editor
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pywebview>=5.0
+Requires-Dist: pyobjc-core<12; sys_platform == "darwin" and python_version < "3.10"
+Requires-Dist: pyobjc-framework-Cocoa<12; sys_platform == "darwin" and python_version < "3.10"
+Requires-Dist: pyobjc-framework-Quartz<12; sys_platform == "darwin" and python_version < "3.10"
+Requires-Dist: pyobjc-framework-Security<12; sys_platform == "darwin" and python_version < "3.10"
+Requires-Dist: pyobjc-framework-UniformTypeIdentifiers<12; sys_platform == "darwin" and python_version < "3.10"
+Requires-Dist: pyobjc-framework-WebKit<12; sys_platform == "darwin" and python_version < "3.10"
+
+# Anno Viz
+
+Anno Viz is a local YOLO annotation viewer and editor for image datasets. It opens a native desktop window backed by a web UI, shows the current image with editable bounding boxes, and includes a thumbnail timeline for moving through the dataset quickly.
+
+## Screenshot
+
+![Anno Viz screenshot](docs/screenshots/anno-viz.png)
+
+## Dataset Layout
+
+Anno Viz expects a dataset directory with this structure:
+
+```text
+dataset/
+  images/
+    image_001.jpg
+    image_002.jpg
+  labels/
+    image_001.txt
+    image_002.txt
+  classes.txt
+```
+
+Labels use standard YOLO text format:
+
+```text
+class_id x_center y_center width height
+```
+
+The coordinate values are normalized from `0` to `1`.
+
+## Install
+
+Create and activate a virtual environment if you want to keep dependencies isolated:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Install Anno Viz and its dependencies from the project root:
+
+```bash
+python3 -m pip install .
+```
+
+This installs the `annoviz` command. If you install outside a virtual environment and your shell cannot find `annoviz`, add your Python user scripts directory to `PATH`. On macOS with the system/Xcode Python this is often:
+
+```bash
+export PATH="$HOME/Library/Python/3.9/bin:$PATH"
+```
+
+For active development, install it in editable mode:
+
+```bash
+python3 -m pip install -e .
+```
+
+`pywebview` is required because the editor opens in a native desktop window. On macOS with Python 3.9, `requirements.txt` pins the PyObjC packages below version 12 because PyObjC 12 may try to build from source and fail on that toolchain.
+
+## Configure Dataset Directory
+
+Set the default dataset directory for the current workspace:
+
+```bash
+annoviz --set-dataset-dir /path/to/dataset
+```
+
+This creates a local workspace config file named `anno_viz_config`. It is ignored by git, so each workspace can point at its own dataset.
+
+You can also use the underscore alias:
+
+```bash
+annoviz --set_dataset_dir /path/to/dataset
+```
+
+## Run
+
+After setting the dataset directory:
+
+```bash
+annoviz
+```
+
+You can also run from source without installing through the compatibility wrappers:
+
+```bash
+python3 app.py
+python3 anno_viz.py
+python3 -m annoviz
+```
+
+To temporarily open a different dataset without changing the saved workspace config:
+
+```bash
+annoviz --dataset-dir /path/to/other/dataset
+annoviz -dataset_dir /path/to/other/dataset
+```
+
+## Optional Paths
+
+Use these when your dataset does not follow the default `images/`, `labels/`, `classes.txt` layout:
+
+```bash
+annoviz \
+  --images-dir /path/to/images \
+  --labels-dir /path/to/labels \
+  --classes-file /path/to/classes.txt
+```
+
+Other useful options:
+
+```bash
+annoviz --start-index 25
+annoviz --port 8765
+annoviz --save-dir /path/to/rendered/previews
+```
+
+## Controls
+
+Control
+
+Action
+
+`n`, Right Arrow
+
+Next image
+
+`b`, Left Arrow
+
+Previous image
+
+`c`
+
+Move back 5 images
+
+`v`
+
+Move forward 2 images
+
+`x`
+
+Move back 10 images
+
+`a`
+
+Toggle add-annotation mode
+
+Drag box
+
+Move or resize an annotation
+
+`Tab`
+
+Select next box
+
+`+`, `-`
+
+Change selected/add class
+
+`0` to `9`
+
+Set selected/add class id
+
+Delete, Backspace
+
+Remove selected box from the label
+
+`s`
+
+Save label edits
+
+`d`
+
+Mark current image for deletion
+
+Click a red thumbnail
+
+Undo pending delete for that image
+
+Apply Deletes
+
+Delete all marked images and matching label files
+
+`q`, Escape, Close
+
+Close the editor
+
+## Delete Flow
+
+Press `d` to mark the current image for deletion. Marked thumbnails are shown in red.
+
+Deletion is not applied immediately. You can undo a pending delete by clicking the red thumbnail. To permanently remove all marked images and their label files, click `Apply Deletes`.
+
+When closing from `q`, Escape, or the `Close` button with pending deletes, Anno Viz asks whether to apply the pending deletes before closing.
+
+## Config
+
+The workspace config file is:
+
+```text
+anno_viz_config
+```
+
+It stores JSON like:
+
+```json
+{
+  "dataset_dir": "/path/to/dataset"
+}
+```
+
+This file is intentionally ignored by git because it is machine/workspace-specific.
+
+## Troubleshooting
+
+If the editor says the dataset directory is not set, run:
+
+```bash
+annoviz --set-dataset-dir /path/to/dataset
+```
+
+If `pywebview` is missing, run:
+
+```bash
+python3 -m pip install .
+```
+
+If no images appear, check that your image files are inside the configured `images/` directory. Supported extensions are handled by the local image collector in `io_utils.py`.

annoviz-0.1.0/README.md

@@ -0,0 +1,229 @@
+# Anno Viz
+
+Anno Viz is a local YOLO annotation viewer and editor for image datasets. It opens a native desktop window backed by a web UI, shows the current image with editable bounding boxes, and includes a thumbnail timeline for moving through the dataset quickly.
+
+## Screenshot
+
+![Anno Viz screenshot](docs/screenshots/anno-viz.png)
+
+## Dataset Layout
+
+Anno Viz expects a dataset directory with this structure:
+
+```text
+dataset/
+  images/
+    image_001.jpg
+    image_002.jpg
+  labels/
+    image_001.txt
+    image_002.txt
+  classes.txt
+```
+
+Labels use standard YOLO text format:
+
+```text
+class_id x_center y_center width height
+```
+
+The coordinate values are normalized from `0` to `1`.
+
+## Install
+
+Create and activate a virtual environment if you want to keep dependencies isolated:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Install Anno Viz and its dependencies from the project root:
+
+```bash
+python3 -m pip install .
+```
+
+This installs the `annoviz` command. If you install outside a virtual environment and your shell cannot find `annoviz`, add your Python user scripts directory to `PATH`. On macOS with the system/Xcode Python this is often:
+
+```bash
+export PATH="$HOME/Library/Python/3.9/bin:$PATH"
+```
+
+For active development, install it in editable mode:
+
+```bash
+python3 -m pip install -e .
+```
+
+`pywebview` is required because the editor opens in a native desktop window. On macOS with Python 3.9, `requirements.txt` pins the PyObjC packages below version 12 because PyObjC 12 may try to build from source and fail on that toolchain.
+
+## Configure Dataset Directory
+
+Set the default dataset directory for the current workspace:
+
+```bash
+annoviz --set-dataset-dir /path/to/dataset
+```
+
+This creates a local workspace config file named `anno_viz_config`. It is ignored by git, so each workspace can point at its own dataset.
+
+You can also use the underscore alias:
+
+```bash
+annoviz --set_dataset_dir /path/to/dataset
+```
+
+## Run
+
+After setting the dataset directory:
+
+```bash
+annoviz
+```
+
+You can also run from source without installing through the compatibility wrappers:
+
+```bash
+python3 app.py
+python3 anno_viz.py
+python3 -m annoviz
+```
+
+To temporarily open a different dataset without changing the saved workspace config:
+
+```bash
+annoviz --dataset-dir /path/to/other/dataset
+annoviz -dataset_dir /path/to/other/dataset
+```
+
+## Optional Paths
+
+Use these when your dataset does not follow the default `images/`, `labels/`, `classes.txt` layout:
+
+```bash
+annoviz \
+  --images-dir /path/to/images \
+  --labels-dir /path/to/labels \
+  --classes-file /path/to/classes.txt
+```
+
+Other useful options:
+
+```bash
+annoviz --start-index 25
+annoviz --port 8765
+annoviz --save-dir /path/to/rendered/previews
+```
+
+## Controls
+
+Control
+
+Action
+
+`n`, Right Arrow
+
+Next image
+
+`b`, Left Arrow
+
+Previous image
+
+`c`
+
+Move back 5 images
+
+`v`
+
+Move forward 2 images
+
+`x`
+
+Move back 10 images
+
+`a`
+
+Toggle add-annotation mode
+
+Drag box
+
+Move or resize an annotation
+
+`Tab`
+
+Select next box
+
+`+`, `-`
+
+Change selected/add class
+
+`0` to `9`
+
+Set selected/add class id
+
+Delete, Backspace
+
+Remove selected box from the label
+
+`s`
+
+Save label edits
+
+`d`
+
+Mark current image for deletion
+
+Click a red thumbnail
+
+Undo pending delete for that image
+
+Apply Deletes
+
+Delete all marked images and matching label files
+
+`q`, Escape, Close
+
+Close the editor
+
+## Delete Flow
+
+Press `d` to mark the current image for deletion. Marked thumbnails are shown in red.
+
+Deletion is not applied immediately. You can undo a pending delete by clicking the red thumbnail. To permanently remove all marked images and their label files, click `Apply Deletes`.
+
+When closing from `q`, Escape, or the `Close` button with pending deletes, Anno Viz asks whether to apply the pending deletes before closing.
+
+## Config
+
+The workspace config file is:
+
+```text
+anno_viz_config
+```
+
+It stores JSON like:
+
+```json
+{
+  "dataset_dir": "/path/to/dataset"
+}
+```
+
+This file is intentionally ignored by git because it is machine/workspace-specific.
+
+## Troubleshooting
+
+If the editor says the dataset directory is not set, run:
+
+```bash
+annoviz --set-dataset-dir /path/to/dataset
+```
+
+If `pywebview` is missing, run:
+
+```bash
+python3 -m pip install .
+```
+
+If no images appear, check that your image files are inside the configured `images/` directory. Supported extensions are handled by the local image collector in `io_utils.py`.

annoviz-0.1.0/annoviz/__init__.py

@@ -0,0 +1,3 @@
+"""Anno Viz package."""
+
+__version__ = "0.1.0"

annoviz-0.1.0/annoviz/__main__.py

@@ -0,0 +1,5 @@
+from .app import main
+
+
+if __name__ == "__main__":
+    main()

annoviz-0.1.0/annoviz/app.py

@@ -0,0 +1,167 @@
+from pathlib import Path
+import argparse
+import json
+
+
+CONFIG_FILE = "anno_viz_config"
+LEGACY_DATASET_PATH_FILE = "anno_viz_datasetpath.txt"
+
+DATASET_DIR_INSTRUCTIONS = """Dataset directory is not set.
+
+Set a default dataset directory for this workspace:
+    annoviz --set-dataset-dir /path/to/dataset
+
+Or temporarily visualize a different dataset for one run:
+    annoviz --dataset-dir /path/to/dataset
+    annoviz -dataset_dir /path/to/dataset
+
+The dataset directory should contain:
+    images/
+    labels/
+    classes.txt
+"""
+
+
+def workspace_config_file():
+    return Path.cwd() / CONFIG_FILE
+
+
+def workspace_legacy_config_file():
+    return Path.cwd() / LEGACY_DATASET_PATH_FILE
+
+
+def is_git_workspace(workspace_dir):
+    return (workspace_dir / ".git").exists()
+
+
+def ensure_config_gitignored(workspace_dir):
+    if not is_git_workspace(workspace_dir):
+        return False
+
+    gitignore_path = workspace_dir / ".gitignore"
+    entry = CONFIG_FILE
+
+    if not gitignore_path.exists():
+        gitignore_path.write_text(f"{entry}\n", encoding="utf-8")
+        return True
+
+    content = gitignore_path.read_text(encoding="utf-8")
+    lines = [line.strip() for line in content.splitlines()]
+    if entry in lines:
+        return False
+
+    separator = "" if content.endswith("\n") or not content else "\n"
+    with gitignore_path.open("a", encoding="utf-8") as gitignore:
+        gitignore.write(f"{separator}{entry}\n")
+    return True
+
+
+def normalize_dataset_dir(path):
+    path = Path(path).expanduser()
+    if not path.is_absolute():
+        path = Path.cwd() / path
+    return path.resolve()
+
+
+def write_workspace_config(config_file, dataset_dir):
+    config = {
+        "dataset_dir": str(dataset_dir),
+    }
+    config_file.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+
+
+def read_dataset_path_text(path_file):
+    raw_path = path_file.read_text(encoding="utf-8").strip()
+    if not raw_path:
+        return None
+
+    path = Path(raw_path).expanduser()
+    if not path.is_absolute():
+        path = path_file.parent / path
+    return path.resolve()
+
+
+def read_workspace_dataset_dir(config_file):
+    if config_file.exists():
+        raw_config = config_file.read_text(encoding="utf-8").strip()
+        if not raw_config:
+            return None
+
+        try:
+            config = json.loads(raw_config)
+        except json.JSONDecodeError:
+            return read_dataset_path_text(config_file)
+
+        dataset_dir = config.get("dataset_dir")
+        if not dataset_dir:
+            return None
+
+        path = Path(dataset_dir).expanduser()
+        if not path.is_absolute():
+            path = config_file.parent / path
+        return path.resolve()
+
+    legacy_path_file = workspace_legacy_config_file()
+    if legacy_path_file.exists():
+        return read_dataset_path_text(legacy_path_file)
+
+    return None
+
+
+def main():
+    parser = argparse.ArgumentParser(description="View/edit YOLO annotations on generated images")
+    parser.add_argument(
+        "--set-dataset-dir",
+        "--set_dataset_dir",
+        dest="set_dataset_dir",
+        default=None,
+        type=Path,
+        help=f"Save the default dataset root to {CONFIG_FILE} in the current workspace.",
+    )
+    parser.add_argument(
+        "--dataset-dir",
+        "--dataset_dir",
+        "-dataset_dir",
+        dest="dataset_dir",
+        default=None,
+        type=Path,
+        help="Dataset root for this run.",
+    )
+    parser.add_argument("--images-dir", default=None, type=Path)
+    parser.add_argument("--labels-dir", default=None, type=Path)
+    parser.add_argument("--classes-file", default=None, type=Path)
+    parser.add_argument("--save-dir", default=None, type=Path)
+    parser.add_argument("--start-index", default=0, type=int)
+    parser.add_argument("--port", default=0, type=int, help="Local web UI port. Defaults to a free port.")
+
+    args = parser.parse_args()
+    config_file = workspace_config_file()
+    if args.set_dataset_dir is not None:
+        dataset_dir = normalize_dataset_dir(args.set_dataset_dir)
+        write_workspace_config(config_file, dataset_dir)
+        print(f"saved dataset directory to {config_file}: {dataset_dir}")
+        legacy_path_file = workspace_legacy_config_file()
+        if legacy_path_file.exists():
+            legacy_path_file.unlink()
+        ensure_config_gitignored(config_file.parent)
+        return
+
+    dataset_dir = args.dataset_dir.expanduser() if args.dataset_dir is not None else read_workspace_dataset_dir(config_file)
+    if dataset_dir is None:
+        parser.exit(2, f"error: {DATASET_DIR_INSTRUCTIONS}\n")
+
+    dataset_dir = normalize_dataset_dir(dataset_dir)
+    from .web_editor import visualize
+
+    visualize(
+        images_dir=args.images_dir or dataset_dir / "images",
+        labels_dir=args.labels_dir or dataset_dir / "labels",
+        classes_file=args.classes_file or dataset_dir / "classes.txt",
+        save_dir=args.save_dir,
+        start_index=args.start_index,
+        port=args.port,
+    )
+
+
+if __name__ == "__main__":
+    main()