diff --git a/.githooks/pre-commit b/.githooks/pre-commit
deleted file mode 100755
index 32097586..00000000
--- a/.githooks/pre-commit
+++ /dev/null
@@ -1,83 +0,0 @@
-#!/usr/bin/env python3
-"""Pre-commit hook: keep notebook outputs clear and bootstrap cells in sync.
-
-Activated once per machine via `git config core.hooksPath .githooks`
-(see docs/notebooks/README.md for the full explanation). Fixes any affected
-notebook in place and re-stages it, so the commit proceeds with the fix already
-applied -- no interruption, no separate re-commit step.
-"""
-
-import subprocess
-import sys
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parent.parent
-NOTEBOOKS_DIR = REPO_ROOT / "docs" / "notebooks"
-
-
-def staged_files(pattern: str) -> list[str]:
- result = subprocess.run(
- ["git", "diff", "--cached", "--name-only", "--diff-filter=ACMR", "--", pattern],
- cwd=REPO_ROOT,
- capture_output=True,
- text=True,
- check=True,
- )
- return [line for line in result.stdout.splitlines() if line]
-
-
-def main() -> int:
- if not NOTEBOOKS_DIR.exists():
- return 0
-
- staged_notebooks = staged_files("docs/notebooks/*.ipynb")
- template_staged = bool(staged_files("docs/notebooks/_mvtb_nb_bootstrap.py"))
-
- # Output-clearing only ever touches notebooks actually staged for this commit.
- output_targets = staged_notebooks
-
- # Bootstrap-cell regeneration also has to cover every notebook when the
- # template itself changed -- otherwise the other notebooks go stale and CI
- # fails on files this commit never touched.
- if template_staged:
- bootstrap_targets = sorted(
- str(p.relative_to(REPO_ROOT)) for p in NOTEBOOKS_DIR.glob("*.ipynb")
- )
- else:
- bootstrap_targets = staged_notebooks
-
- if not output_targets and not bootstrap_targets:
- return 0
-
- changed_paths: set[str] = set()
-
- try:
- if output_targets:
- paths = [str(REPO_ROOT / t) for t in output_targets]
- subprocess.run(
- [sys.executable, str(NOTEBOOKS_DIR / "clear_outputs.py"), *paths],
- cwd=REPO_ROOT,
- check=True,
- )
- changed_paths.update(paths)
-
- if bootstrap_targets:
- paths = [str(REPO_ROOT / t) for t in bootstrap_targets]
- subprocess.run(
- [sys.executable, str(NOTEBOOKS_DIR / "sync_bootstrap.py"), *paths],
- cwd=REPO_ROOT,
- check=True,
- )
- changed_paths.update(paths)
- except subprocess.CalledProcessError:
- print("pre-commit hook: notebook cleanup failed unexpectedly", file=sys.stderr)
- return 1
-
- if changed_paths:
- subprocess.run(["git", "add", "--", *sorted(changed_paths)], cwd=REPO_ROOT, check=True)
-
- return 0
-
-
-if __name__ == "__main__":
- sys.exit(main())
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 4fa08e36..b02b70e4 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -40,10 +40,12 @@ jobs:
with:
python-version: "3.12"
- - name: Check notebook bootstrap cells and outputs are in sync
+ # the hooks of .pre-commit-config.yaml, from rvc-ecosystem: notebook outputs are
+ # cleared, the generated bootstrap cell is current, the first cell is well formed
+ - name: Check the notebooks
run: |
- python docs/notebooks/sync_bootstrap.py --check
- python docs/notebooks/clear_outputs.py --check
+ python -m pip install pre-commit
+ pre-commit run --all-files --show-diff-on-failure
- name: Install system dependencies
run: sudo apt-get install -y graphviz
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 00000000..1965abe7
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,11 @@
+# The checks that keep the notebooks in docs/notebooks in step, from rvc-ecosystem:
+# outputs cleared, the generated bootstrap cell up to date, the first cell well formed.
+# See docs/notebooks/README.md. Install the hooks once with: pre-commit install
+# CI runs the same hooks (docs.yml).
+repos:
+ - repo: https://github.com/petercorke/rvc-ecosystem
+ rev: d21147cc356c167511e4b92b43edc54be35a37d9 # main on 2026-11-20; a tag (v1) once there is one
+ hooks:
+ - id: notebooks-clear-outputs
+ - id: notebooks-sync-bootstrap
+ - id: notebooks-first-cell
diff --git a/docs/lite/browser_check/README.md b/docs/lite/browser_check/README.md
index 1b67ad47..484ebfe3 100644
--- a/docs/lite/browser_check/README.md
+++ b/docs/lite/browser_check/README.md
@@ -2,7 +2,7 @@
Opens the JupyterLite site in real browsers (Playwright: Chromium and WebKit, the
engine behind Safari), waits for the Pyodide kernel, runs `intro.ipynb`'s bootstrap
-cell, and requires its `Running in browser using MVTB v...` line. It also fails if
+cell, and requires its `Running in browser using machinevision-toolbox-python v...` line. It also fails if
JupyterLab itself does not start (`Plugin '...' failed to activate`), which happens
before any kernel exists.
diff --git a/docs/lite/browser_check/check_lite_in_browser.py b/docs/lite/browser_check/check_lite_in_browser.py
index c4ef0cc5..4cb347cf 100644
--- a/docs/lite/browser_check/check_lite_in_browser.py
+++ b/docs/lite/browser_check/check_lite_in_browser.py
@@ -3,7 +3,7 @@
Opens a notebook in a fresh browser context, waits for the Pyodide kernel, runs the
notebook's bootstrap cell (the first code cell) and requires its status line
-``Running in browser using MVTB v...`` to appear. Also fails if JupyterLab itself
+``Running in browser using machinevision-toolbox-python v...`` to appear. Also fails if JupyterLab itself
could not start (``Plugin '...' failed to activate`` console errors), which happens
before any kernel exists and which the Node/Pyodide install check cannot see.
@@ -26,7 +26,7 @@
from playwright.sync_api import TimeoutError as PlaywrightTimeout
from playwright.sync_api import sync_playwright
-SUCCESS_TEXT = "Running in browser using MVTB"
+SUCCESS_TEXT = "Running in browser using machinevision-toolbox-python"
APP_FAILURE_MARKERS = ("failed to activate", "No setting registry")
diff --git a/docs/lite/wasm_check/check_pyodide_install.mjs b/docs/lite/wasm_check/check_pyodide_install.mjs
index f71ec21b..9905e6be 100644
--- a/docs/lite/wasm_check/check_pyodide_install.mjs
+++ b/docs/lite/wasm_check/check_pyodide_install.mjs
@@ -54,15 +54,17 @@ sys.path.insert(0, "/")
import micropip
import _mvtb_nb_bootstrap as bootstrap
-# Test-only scaffolding: redirect the one HTTP/relative-URL install call to
-# the wheel already mounted in Pyodide's own virtual filesystem, so this
-# check doesn't need to fake a browser Web Worker's base URL (see this
-# file's module docstring for why that's out of scope here). Everything
-# else -- the seed-package installs, which is what this check actually
-# exists to catch drift in -- runs completely unmodified.
+# Test-only scaffolding: in JupyterLite the bootstrap installs the toolbox with
+# piplite, which finds the wheel built with the site. Node has no piplite, so the
+# bootstrap falls back to micropip, which would install the last release from PyPI.
+# Redirect that one install to the wheel already mounted in Pyodide's own virtual
+# filesystem, so the check tests the wheel just built and doesn't need to fake a
+# browser Web Worker's base URL (see this file's module docstring for why that's out
+# of scope here). Everything else -- the seed-package installs, which is what this
+# check actually exists to catch drift in -- runs completely unmodified.
_real_install = micropip.install
async def _redirect_wheel_install(requirements, **kwargs):
- if isinstance(requirements, str) and requirements.startswith("pypi/"):
+ if requirements == bootstrap.PACKAGE:
requirements = "emfs:/${wheelName}"
return await _real_install(requirements, **kwargs)
micropip.install = _redirect_wheel_install
diff --git a/docs/notebooks/IBVS.ipynb b/docs/notebooks/IBVS.ipynb
index 219ba218..511ce070 100644
--- a/docs/notebooks/IBVS.ipynb
+++ b/docs/notebooks/IBVS.ipynb
@@ -2,6 +2,7 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "67784fbc",
"metadata": {
"id": "vf-Nuk3fmDLL"
},
@@ -9,7 +10,7 @@
"
\n",
" \n",
" Image-based Visual Servo | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -20,6 +21,7 @@
},
{
"cell_type": "markdown",
+ "id": "960f06dc",
"metadata": {},
"source": [
"## Configuring the Jupyter environment\n",
@@ -29,106 +31,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
- "\n",
- "\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
- "\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
- "\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
- "\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
+ "\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
+ "\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
+ "\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -137,6 +136,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "8aafa7ee",
"metadata": {
"id": "o29Pu_OwmDLP"
},
@@ -156,6 +156,7 @@
},
{
"cell_type": "markdown",
+ "id": "4d62ef85",
"metadata": {
"id": "3XYFjQQ-mDLQ"
},
@@ -167,6 +168,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "045deab0",
"metadata": {
"id": "ggP10tO5mDLR"
},
@@ -180,6 +182,7 @@
},
{
"cell_type": "markdown",
+ "id": "6210087d",
"metadata": {
"id": "pfrZalSAmDLS"
},
@@ -190,6 +193,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ef5687df",
"metadata": {
"id": "YmYUwsfLmDLS"
},
@@ -200,6 +204,7 @@
},
{
"cell_type": "markdown",
+ "id": "4935eceb",
"metadata": {
"id": "GLw-W7R9mDLT"
},
@@ -210,6 +215,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ebc8afaf",
"metadata": {
"id": "5YpAIqZbmDLT"
},
@@ -221,6 +227,7 @@
},
{
"cell_type": "markdown",
+ "id": "a6c54920",
"metadata": {
"id": "vJ67xblqmDLU"
},
@@ -231,6 +238,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "fde4e99f",
"metadata": {
"code_folding": [],
"id": "IFkggXiVmDLU",
@@ -257,6 +265,7 @@
},
{
"cell_type": "markdown",
+ "id": "76c2a656",
"metadata": {
"id": "qK0vBPE9mDLU"
},
@@ -267,6 +276,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "c0ca93a4",
"metadata": {
"id": "7EdpjAsEmDLV"
},
@@ -295,6 +305,7 @@
},
{
"cell_type": "markdown",
+ "id": "314347a9",
"metadata": {
"id": "mjzNpklZmDLV"
},
@@ -305,6 +316,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "2b0d48b5",
"metadata": {
"id": "WzGeYJmrmDLW"
},
@@ -316,6 +328,7 @@
},
{
"cell_type": "markdown",
+ "id": "555911ba",
"metadata": {
"id": "M8AuGtnlmDLW"
},
@@ -326,6 +339,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "d568879e",
"metadata": {
"id": "E4pR5WlbmDLW"
},
@@ -352,6 +366,7 @@
},
{
"cell_type": "markdown",
+ "id": "e867329e",
"metadata": {
"id": "OdLbBECPmDLX"
},
@@ -362,6 +377,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "4b7d6cb8",
"metadata": {
"id": "wsC7_wRFmDLX"
},
@@ -373,6 +389,7 @@
},
{
"cell_type": "markdown",
+ "id": "c64a7a0b",
"metadata": {
"id": "uDlg6v86mDLY"
},
@@ -383,6 +400,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "0c09a941",
"metadata": {
"id": "TrI8QHB7mDLY"
},
@@ -394,6 +412,7 @@
},
{
"cell_type": "markdown",
+ "id": "dc5218bb",
"metadata": {
"id": "dlptJOywmDLY"
},
@@ -404,6 +423,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "3ec02e63",
"metadata": {
"id": "rFZ1IqYkmDLZ"
},
@@ -415,6 +435,7 @@
},
{
"cell_type": "markdown",
+ "id": "88942ad7",
"metadata": {
"id": "6gI7OkNLmDLZ"
},
@@ -427,6 +448,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "276d638b",
"metadata": {
"code_folding": [],
"id": "Z9JAcekRmDLZ"
@@ -456,6 +478,7 @@
},
{
"cell_type": "markdown",
+ "id": "691e38e3",
"metadata": {
"id": "caj8BxkOmDLa"
},
@@ -468,6 +491,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "0b1aec8a",
"metadata": {
"code_folding": [],
"id": "_kguVRKLmDLa"
@@ -504,6 +528,7 @@
},
{
"cell_type": "markdown",
+ "id": "08f607c9",
"metadata": {
"id": "d61QyHZwmDLb"
},
@@ -516,6 +541,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "4b09a55f",
"metadata": {
"id": "YGFvvuNFmDLb"
},
@@ -533,6 +559,7 @@
},
{
"cell_type": "markdown",
+ "id": "13823663",
"metadata": {
"id": "3jqNCP-0mDLb"
},
@@ -545,6 +572,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1acae202",
"metadata": {
"id": "YzVrKKK6vXv6"
},
@@ -557,6 +585,7 @@
},
{
"cell_type": "markdown",
+ "id": "3ede8310",
"metadata": {
"id": "mveO9E_bxggf"
},
@@ -567,6 +596,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ef2189ef",
"metadata": {
"id": "Mzrutm1RmDLc"
},
@@ -580,6 +610,7 @@
},
{
"cell_type": "markdown",
+ "id": "94212fd9",
"metadata": {
"id": "4kdrmqcumDLc"
},
@@ -590,6 +621,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "f9b5e294",
"metadata": {
"id": "DPkWTXktmDLd"
},
@@ -603,6 +635,7 @@
},
{
"cell_type": "markdown",
+ "id": "27e706e9",
"metadata": {
"id": "2dciaz7AmDLd"
},
@@ -616,77 +649,15 @@
}
],
"metadata": {
- "colab": {
- "name": "IBVS.ipynb",
- "provenance": []
- },
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.10.12"
- },
- "toc": {
- "base_numbering": 1,
- "nav_menu": {},
- "number_sections": true,
- "sideBar": true,
- "skip_h1_title": false,
- "title_cell": "Table of Contents",
- "title_sidebar": "Contents",
- "toc_cell": false,
- "toc_position": {},
- "toc_section_display": true,
- "toc_window_display": false
- },
- "varInspector": {
- "cols": {
- "lenName": 16,
- "lenType": 16,
- "lenVar": 40
- },
- "kernels_config": {
- "python": {
- "delete_cmd_postfix": "",
- "delete_cmd_prefix": "del ",
- "library": "var_list.py",
- "varRefreshCmd": "print(var_dic_list())"
- },
- "r": {
- "delete_cmd_postfix": ") ",
- "delete_cmd_prefix": "rm(",
- "library": "var_list.r",
- "varRefreshCmd": "cat(var_dic_list()) "
- }
- },
- "position": {
- "height": "335px",
- "left": "752px",
- "right": "20px",
- "top": "120px",
- "width": "349px"
- },
- "types_to_exclude": [
- "module",
- "function",
- "builtin_function_or_method",
- "instance",
- "_Feature"
- ],
- "window_display": false
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 0
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/README.md b/docs/notebooks/README.md
index 9a9d32df..169cb25c 100644
--- a/docs/notebooks/README.md
+++ b/docs/notebooks/README.md
@@ -95,41 +95,33 @@ Every notebook here has to work in three different environments, each of which n
**All three cases are handled by one file: `_mvtb_nb_bootstrap.py`.** It detects which environment it's in and does whatever that environment needs, ending with a one-line sanity check so a broken environment-detection is obvious at a glance rather than failing mysteriously three cells later:
```
-Running locally using MVTB v2.2.0
-Running on Colab using MVTB v2.2.0
-Running in browser using MVTB v2.2.0
+Running locally using machinevision-toolbox-python v2.2.0
+Running on Colab using machinevision-toolbox-python v2.2.0
+Running in browser using machinevision-toolbox-python v2.2.0
```
Every notebook's first code cell is a copy of that file's content, marked with a `# MVTB_BOOTSTRAP_CELL` comment. It's a *copy*, not an import — Colab can't see sibling files, so the cell has to be fully self-contained, the same way Colab notebooks in this space normally are (this is deliberate; a fancier design that fetched the shared code over the network at runtime was considered and rejected — it would have made every notebook depend on GitHub being reachable just to install itself, which is a worse failure mode than a bit of duplication).
-**The copy is machine-generated, not hand-maintained**, which is the actual point: edit `_mvtb_nb_bootstrap.py` once, then either let the commit hook regenerate every notebook's marked cell for you automatically (silently, as part of `git commit`), or run it by hand:
-```
-python docs/notebooks/sync_bootstrap.py
-```
-A second hook also clears notebook outputs on the way in (`clear_notebook_outputs.sh`'s logic), so committed notebooks stay clean without having to remember that step either.
+**The copy is machine-generated, not hand-maintained**, which is the actual point: edit `_mvtb_nb_bootstrap.py` once and the `notebooks-sync-bootstrap` hook regenerates every notebook's marked cell. `_mvtb_nb_bootstrap.py` is a copy of the canonical template in [rvc-ecosystem](https://github.com/petercorke/rvc-ecosystem/blob/main/notebooks/bootstrap_template.py) with only its repo-specific constants changed, so RTB, MVTB and bdsim install the same way. The tools are shared too: they are [pre-commit](https://pre-commit.com) hooks from rvc-ecosystem, configured in `.pre-commit-config.yaml`, and nothing from them is copied into this repo.
-**Enforcement happens via a plain git hook, not the `pre-commit` framework.** We wanted here a fully mechanical, deterministic regeneration shouldn't need a manual re-commit every single time. So this repo uses a plain git hook instead, versioned at `.githooks/pre-commit`.
+| Hook | Does |
+| :--- | :--- |
+| `notebooks-clear-outputs` | clears outputs and execution counts, sets the same kernel in every notebook, and keeps only the `mvtb_bootstrap` metadata |
+| `notebooks-sync-bootstrap` | regenerates the bootstrap cell of every notebook from `_mvtb_nb_bootstrap.py` |
+| `notebooks-first-cell` | the first cell is markdown, and its logo has a width, a height and `style="height:auto"` |
### One-time setup (per machine)
-This is a *local* git setting — it doesn't come along when you clone the repo, and isn't shared by git config, so it needs doing once on every machine you commit from:
-```
-git config core.hooksPath .githooks
```
-That's the only step — `.githooks/pre-commit` is already committed with its executable bit set (git tracks that), and it only needs the Python already on your `PATH` plus the stdlib (no extra `pip install`, no `pre-commit` package). To check it's active:
+pip install pre-commit
+pre-commit install
```
-git config --get core.hooksPath # should print .githooks
-```
-Nothing is enforced on a machine where this hasn't been set — CI is the backstop for that case, not the primary mechanism.
-The hook stays quiet when there's nothing to do, and only speaks up when it actually changes something:
+After that the hooks run on `git commit`, and fix a notebook in place (re-add it and commit again). To run them by hand on every notebook:
```
-docs/notebooks/gamma.ipynb: found output, clearing it
-docs/notebooks/camera.ipynb: bootstrap cell out of date, regenerating
+pre-commit run --all-files
```
-so an ordinary commit scrolls past without any noise, but one that got silently fixed for you still leaves a visible trace — a lightweight way to notice the safety net firing without it ever stopping you.
-
-If a notebook's bootstrap cell falls out of sync anyway (hook not installed on this machine, notebook edited elsewhere), CI catches it on the PR — a job re-runs the generator in check-only mode across every notebook and fails if anything doesn't match.
+Nothing is enforced on a machine where the hooks are not installed. CI runs the same command on every PR (the docs workflow), so a notebook that is out of step fails there.
**Why this exists at all:** before this, 13 of the 16 notebooks each had their own hand-pasted, slightly-drifted copy of the Colab-install snippet, and the JupyterLite demo notebook had its own bespoke version with a manually-maintained dependency list. That's exactly how machinevision-toolbox-python 2.2.0 shipped a broken "Try it Now" demo — `tqdm` was added as a real dependency but nobody updated the one notebook's hand-typed install list, and nothing tested it before release. One template, generated everywhere, checked by CI, closes that gap.
diff --git a/docs/notebooks/_mvtb_nb_bootstrap.py b/docs/notebooks/_mvtb_nb_bootstrap.py
index 3e7cbcb7..ddb61ebc 100644
--- a/docs/notebooks/_mvtb_nb_bootstrap.py
+++ b/docs/notebooks/_mvtb_nb_bootstrap.py
@@ -1,64 +1,143 @@
-"""Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.
+"""Environment bootstrap for a toolbox's Jupyter notebooks: the canonical template.
-Installs the toolbox (and reports how) across the three environments a notebook in
-this folder might run in: a local Jupyter/VS Code install, Google Colab, and
-JupyterLite (Pyodide/WASM, in-browser).
+Installs the toolbox (and reports how) across the three environments a notebook
+might run in: a local Jupyter/VS Code install, Google Colab, and JupyterLite
+(Pyodide/WASM, in-browser).
-This file is the single source of truth for that logic. Every notebook's own
-bootstrap cell is a generated copy of this file's content, produced by
-sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.
+This is the reference copy for the big 3 (RTB, MVTB, bdsim). A repo keeps its own
+copy as ``docs/notebooks/__nb_bootstrap.py``, changes only the constants
+under "Repo-specific" below, and uses ``sync_bootstrap.py`` to paste it into every
+notebook as a generated cell, because Colab fetches only the single .ipynb it is
+opened from and cannot see sibling files. See ``notebooks.md`` section 3.
+
+Derived from RTB's ``_rtb_nb_bootstrap.py`` (2026-11-02, with the Colab backend-list fix, RTB#922), which is the one that has
+been tested in a real JupyterLite site and on Colab. MVTB's differs, see
+petercorke/machinevision-toolbox-python#160; bdsim has no bootstrap yet.
"""
-import subprocess
+import subprocess # nosec B404 - only to run pip, below
import sys
-from pathlib import Path
+# --- Repo-specific: the only part a repo should change -----------------------------
+
+# the PyPI name of the toolbox, and the name it is imported under
+PACKAGE = "machinevision-toolbox-python"
+IMPORT_NAME = "machinevisiontoolbox"
+
+# Where the development version lives, for a notebook that needs more than the release on
+# PyPI has (see ``min_version``). None if the repo has no such fallback.
+GIT_URL: str | None = "https://github.com/petercorke/machinevision-toolbox-python"
+
+# JupyterLite only: packages installed, with their dependencies, before the toolbox.
+# Everything the notebooks' plotting needs that Pyodide does not already have.
+JL_PACKAGES = [
+ "numpy",
+ "scipy",
+ "matplotlib",
+ "pillow",
+ "typing_extensions",
+ "opencv-python",
+ "ansitable",
+ "mvtb-data",
+ "tqdm",
+ "requests",
+ "ipywidgets",
+ "spatialmath-python",
+ "pgraph-python",
+]
+
+# JupyterLite only: packages installed with deps=False before everything else, for a
+# dependency whose normal resolution fails in Pyodide. Empty now: spatialmath-python
+# <= 1.1.18 listed pre-commit, a dev tool, as a runtime dependency, which needs a
+# newer packaging than Pyodide's, and had to be listed here
+# (rai-opensource/spatialmath-python#250). 1.1.19 fixed it, so a repo that requires
+# spatialmath-python>=1.1.19 needs no entry.
+JL_NO_DEPS: list[str] = []
+
+# JupyterLite only: install the toolbox itself with deps=False, for a toolbox with a
+# dependency that Pyodide does not have (MVTB's opencv-contrib-python). Everything it
+# needs must then be listed in JL_PACKAGES, since nothing is resolved for it. Leave
+# False unless the toolbox cannot be installed with its dependencies.
+JL_PACKAGE_NO_DEPS = True
+
+# extras of the toolbox that need more than Pyodide has, installed in JupyterLite as
+# these packages instead of through the extra: extra name -> packages
+JL_EXTRAS: dict[str, list[str]] = {}
+
+# Colab only: packages installed with the toolbox. Colab does not ship ipympl,
+# which the notebooks select with %matplotlib ipympl.
+COLAB_PACKAGES: list[str] = []
+
+# ---------------------------------------------------------------------------------
-async def ensure_installed() -> bool:
- """Install machinevision-toolbox-python if needed, and report the environment.
+def _version_of(package: str, module) -> str:
+ """The installed version of the package: its metadata, else its ``__version__``."""
+ import importlib.metadata
+
+ try:
+ return importlib.metadata.version(package)
+ except importlib.metadata.PackageNotFoundError:
+ return str(getattr(module, "__version__", "unknown"))
+
+
+def _older(version: str, required: str) -> bool:
+ """True if ``version`` is older than ``required``; False if they cannot be compared."""
+ try:
+ from packaging.version import InvalidVersion, Version
+
+ return Version(version) < Version(required)
+ except (ImportError, InvalidVersion):
+ return False
+
+
+async def ensure_installed(
+ extras: tuple[str, ...] | list[str] = (),
+ packages: tuple[str, ...] | list[str] = (),
+ min_version: str | None = None,
+) -> bool:
+ """Install the toolbox if needed, and report the environment.
+
+ The arguments are set per notebook in its metadata (``_bootstrap``) and
+ passed here by the generated cell.
+
+ :param extras: toolbox extras the notebook needs, for example ``["ik"]``
+ :param packages: other packages the notebook needs, for example ``["control"]`` or
+ another toolbox. Installed in JupyterLite and on Colab; locally the cell only
+ says which are missing
+ :param min_version: the oldest version of the toolbox the notebook works with. On
+ Colab, if the release on PyPI is older (a notebook that uses what the next
+ release will have) the cell installs the development version from ``GIT_URL``
+ instead and says so. Locally it says what to run. In JupyterLite there is no
+ check, since the site's wheel was built from the same commit as the notebook
:returns: True if running on Google Colab, False otherwise.
"""
if sys.platform == "emscripten":
- import micropip
+ # In JupyterLite, piplite looks in this site's own package index first, so the
+ # toolbox it installs is the wheel that was built with the site. micropip
+ # alone cannot see that index and would install the last release from PyPI.
+ # (There is no /pypi folder in the kernel to glob for a wheel.) Outside
+ # JupyterLite, for example a test under Node, there is no piplite.
+ try:
+ import piplite
- await micropip.install(
- [
- "opencv-python",
- "ansitable",
- "mvtb-data",
- "tqdm",
- "requests",
- "ipywidgets",
- # runtime dependencies of spatialmath-python and pgraph-python,
- # listed here because those two are installed with deps=False below
- "numpy",
- "scipy",
- "matplotlib",
- "typing_extensions",
- ]
- )
- # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime
- # dependency; its virtualenv requires packaging>=26.3, which conflicts with
- # the packaging 24.2 built into Pyodide, so a normal resolve fails.
- # pgraph-python depends on spatialmath-python, so it needs the same
- # treatment. Remove once a spatialmath release without that dependency is
- # out (rai-opensource/spatialmath-python#250) and install both normally.
- await micropip.install(
- ["spatialmath-python", "pgraph-python"],
- deps=False,
- )
- import cv2 # noqa: F401 - force cv2 into module registry before toolbox import
-
- wheels = sorted(Path("/pypi").glob("machinevision_toolbox_python-*.whl"))
- if wheels:
- # Prefer the wheel bundled with this JupyterLite site. Relative,
- # not absolute: a leading slash resolves against the origin, not
- # this site's own base URL (a GitHub Pages project subpath).
- await micropip.install(f"pypi/{wheels[-1].name}", deps=False)
- else:
- # Fall back to PyPI when running outside the published site layout.
- await micropip.install("machinevision-toolbox-python", deps=False)
+ install = piplite.install
+ except ImportError:
+ import micropip
+
+ install = micropip.install
+
+ print(f"Installing {PACKAGE}, this takes a short time...", flush=True)
+ for name in JL_NO_DEPS:
+ await install(name, deps=False)
+ for name in JL_PACKAGES:
+ await install(name)
+ for extra in extras:
+ for name in JL_EXTRAS.get(extra, []):
+ await install(name)
+ for name in packages:
+ await install(name)
+ await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)
where, colab = "in browser", False
else:
try:
@@ -66,25 +145,93 @@ async def ensure_installed() -> bool:
except ImportError:
where, colab = "locally", False
else:
- print("Installing machinevision-toolbox-python...")
- subprocess.run(
- [
- sys.executable,
- "-m",
- "pip",
- "install",
- "-q",
- "machinevision-toolbox-python",
- ],
+ print(f"Installing {PACKAGE}, this takes a short time...", flush=True)
+ requirement = PACKAGE
+ if extras:
+ requirement += "[" + ",".join(extras) + "]"
+ # sys.executable is this kernel, so pip installs into it and not into whatever
+ # "pip" is first on PATH. extras and packages are the notebook's own metadata,
+ # as with "!pip install"; pip also reads its own PIP_* settings.
+ subprocess.run( # nosec B603 # nosemgrep: python.lang.security.audit.dangerous-subprocess-use-audit.dangerous-subprocess-use-audit
+ [sys.executable, "-m", "pip", "install", "-q", requirement]
+ + list(packages)
+ + COLAB_PACKAGES,
check=True,
)
+ # matplotlib renames the module://ipympl... backend to "widget", and looks
+ # it up in a list of backends that it builds once, from the installed
+ # packages, the first time it needs it. Colab imported matplotlib before
+ # ipympl was installed, so %matplotlib ipympl is rejected ("... is not a
+ # valid value for backend") until the session restarts. Make matplotlib
+ # build the list again. Clearing the registry is what its own tests do,
+ # and it is needed: only resetting the flag registers the backends that
+ # were already there (matplotlib-inline's) twice, which is an error.
+ # _clear is private, hence the guards.
+ try:
+ from matplotlib.backends import backend_registry
+ except ImportError:
+ pass # an older matplotlib has no registry to refresh
+ else:
+ clear = getattr(backend_registry, "_clear", None)
+ if clear is not None:
+ clear()
+
+ # ipympl figures need Colab's custom widget manager, enabled before the
+ # first figure is created.
+ from google.colab import output
+
+ output.enable_custom_widget_manager()
where, colab = "on Colab", True
- import cv2
+ import importlib
- import machinevisiontoolbox
+ module = importlib.import_module(IMPORT_NAME)
+ version = _version_of(PACKAGE, module)
+
+ if colab and min_version is not None and _older(version, min_version) and GIT_URL:
+ # The release on PyPI is older than this notebook needs. The package is pure
+ # Python in the repos that use this, so installing from GitHub is quick. Its
+ # dependencies are in already. Reinstall even if the version number is the
+ # same, since the development version often has the number of the last release.
+ print(
+ f"{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub..."
+ )
+ # This runs whatever is on GIT_URL's main branch: the point of the fallback, and a
+ # choice of trust.
+ subprocess.run( # nosec B603 # nosemgrep: python.lang.security.audit.dangerous-subprocess-use-audit.dangerous-subprocess-use-audit
+ [
+ sys.executable,
+ "-m",
+ "pip",
+ "install",
+ "-q",
+ "--force-reinstall",
+ "--no-deps",
+ f"{PACKAGE} @ git+{GIT_URL}@main",
+ ],
+ check=True,
+ )
+ importlib.invalidate_caches()
+ version = _version_of(PACKAGE, module)
+ where += ", development version from GitHub"
+
+ if not colab and where == "locally":
+ import importlib.metadata
+
+ for name in packages:
+ try:
+ importlib.metadata.version(name)
+ except importlib.metadata.PackageNotFoundError:
+ print(f"This notebook needs {name}: pip install {name}")
+
+ if (
+ min_version is not None
+ and where in ("locally", "on Colab")
+ and _older(version, min_version)
+ ):
+ print(
+ f"This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}"
+ )
- version = getattr(machinevisiontoolbox, "__version__", "unknown")
- opencv_version = getattr(cv2, "__version__", "unknown")
- print(f"Running {where} using MVTB v{version} with OpenCV {opencv_version}")
+ print(f"Running {where} using {PACKAGE} v{version}")
return colab
diff --git a/docs/notebooks/calibration.ipynb b/docs/notebooks/calibration.ipynb
index cfb406f3..15cf0e5e 100644
--- a/docs/notebooks/calibration.ipynb
+++ b/docs/notebooks/calibration.ipynb
@@ -2,12 +2,13 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "9762a351",
"metadata": {},
"source": [
"\n",
" \n",
" Camera Calibration using 2D images | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -18,106 +19,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
- "\n",
- "\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
"\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
"\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
"\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -126,6 +124,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "76f16d4c",
"metadata": {},
"outputs": [],
"source": [
@@ -136,6 +135,7 @@
},
{
"cell_type": "markdown",
+ "id": "cd02df70",
"metadata": {},
"source": [
"The calibration process simply requires a set of images, that contain a chequerboard of known dimensions, shown in various orientations and distance from the camera.\n",
@@ -146,6 +146,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "d78d8319",
"metadata": {},
"outputs": [],
"source": [
@@ -156,6 +157,7 @@
},
{
"cell_type": "markdown",
+ "id": "3d9e6fc7",
"metadata": {},
"source": [
"OpenCV provides a function to automatically find the chequerboards. Given the size of each square, 25mm in this case, we can estimate the camera intrinsic parameters and the lens distortion model parameters"
@@ -164,6 +166,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1fd449df",
"metadata": {},
"outputs": [],
"source": [
@@ -172,6 +175,7 @@
},
{
"cell_type": "markdown",
+ "id": "c92001ed",
"metadata": {},
"source": [
"The camera intrinsic matrix is"
@@ -180,6 +184,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "53a564fa",
"metadata": {},
"outputs": [],
"source": [
@@ -188,6 +193,7 @@
},
{
"cell_type": "markdown",
+ "id": "917ce96b",
"metadata": {},
"source": [
"The image centre is given by the top two numbers in the right-hand column"
@@ -196,6 +202,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "669f22cc",
"metadata": {},
"outputs": [],
"source": [
@@ -204,6 +211,7 @@
},
{
"cell_type": "markdown",
+ "id": "a4c739a0",
"metadata": {},
"source": [
"which we can compare to the coordinates of the centre pixel of the image"
@@ -212,6 +220,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ffe3eb30",
"metadata": {},
"outputs": [],
"source": [
@@ -220,6 +229,7 @@
},
{
"cell_type": "markdown",
+ "id": "66c4cf56",
"metadata": {},
"source": [
"They are somewhat different, and that tells us that the optical axis of the camera does not pass through the middle pixel of the image. This is pretty common with most real cameras, so it's never good to assume that's where the principal point is.\n",
@@ -230,6 +240,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "2f419c56",
"metadata": {},
"outputs": [],
"source": [
@@ -244,6 +255,7 @@
},
{
"cell_type": "markdown",
+ "id": "cc9f4e24",
"metadata": {},
"source": [
"The chequerboard is at the origin (0,0,0) and its z-axis is pointing into the surface of the board."
@@ -251,6 +263,7 @@
},
{
"cell_type": "markdown",
+ "id": "24210209",
"metadata": {},
"source": [
"Now let's look at the estimated distortion data. The first three numbers are the coefficients of the radial distortion polynomial, while the last two numbers are the coefficients of the tangential distortion polynomial."
@@ -259,6 +272,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "7ab38f09",
"metadata": {},
"outputs": [],
"source": [
@@ -267,6 +281,7 @@
},
{
"cell_type": "markdown",
+ "id": "e69757b2",
"metadata": {},
"source": [
"We will unpack the camera parameters and distortion coefficients into scalar variables to make the following code easier to follow"
@@ -275,6 +290,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "58b3af87",
"metadata": {},
"outputs": [],
"source": [
@@ -284,6 +300,7 @@
},
{
"cell_type": "markdown",
+ "id": "7f0e883e",
"metadata": {},
"source": [
"The distortion model is explained in more detail in Section 13.6 of **Robotics, Vision & Control: Python**. The strange ordering of the terms in `distortion` is an OpenCV thing. "
@@ -291,6 +308,7 @@
},
{
"cell_type": "markdown",
+ "id": "2a7b75a0",
"metadata": {},
"source": [
"We choose to make the resulting undistorted image the same size as the input images."
@@ -299,6 +317,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "c19854ac",
"metadata": {},
"outputs": [],
"source": [
@@ -307,6 +326,7 @@
},
{
"cell_type": "markdown",
+ "id": "6181a020",
"metadata": {},
"source": [
"the matrices `U` and `V` are coordinate matrices. They have the same dimensions as the image used to create them, and for any pixel coordinate `(u,v)` the coordinate matrices are such that `U[v,u]=u` and `V[v,u]=v`. **Remember that these are NumPy arrays and the indices are reversed!**"
@@ -315,6 +335,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "46d74255",
"metadata": {},
"outputs": [],
"source": [
@@ -323,6 +344,7 @@
},
{
"cell_type": "markdown",
+ "id": "fafc36a6",
"metadata": {},
"source": [
"we convert the image coordinates to retinal image-plane coordinates, actual distances on the sensor chip, in units of metres with respect to the camera's principal point"
@@ -331,6 +353,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "e6c46f93",
"metadata": {},
"outputs": [],
"source": [
@@ -340,6 +363,7 @@
},
{
"cell_type": "markdown",
+ "id": "14a4b083",
"metadata": {},
"source": [
"The radial distance of the pixels from the principal point is simply the Euclidean distance"
@@ -348,6 +372,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "deeb0529",
"metadata": {},
"outputs": [],
"source": [
@@ -356,6 +381,7 @@
},
{
"cell_type": "markdown",
+ "id": "ecb503aa",
"metadata": {},
"source": [
"and the retinal coordinate errors due to distortion are given by (13.15) in **Robotics, Vision & Control: Python**"
@@ -364,6 +390,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "6471def4",
"metadata": {},
"outputs": [],
"source": [
@@ -373,6 +400,7 @@
},
{
"cell_type": "markdown",
+ "id": "a413e54d",
"metadata": {},
"source": [
"So the undistorted coordinates are"
@@ -381,6 +409,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "3f746c92",
"metadata": {},
"outputs": [],
"source": [
@@ -389,6 +418,7 @@
},
{
"cell_type": "markdown",
+ "id": "3e3328a0",
"metadata": {},
"source": [
"and we convert those back to image plane coordinates"
@@ -397,6 +427,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "058160b7",
"metadata": {},
"outputs": [],
"source": [
@@ -406,6 +437,7 @@
},
{
"cell_type": "markdown",
+ "id": "7dfe53cb",
"metadata": {},
"source": [
"Now `Ud[v,u]` and `Vd[v,u]` are the distorted coordinates of the point `(u,v)` and we can use this to warp the image to correct the distortion"
@@ -414,6 +446,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "94b138e1",
"metadata": {},
"outputs": [],
"source": [
@@ -424,6 +457,7 @@
},
{
"cell_type": "markdown",
+ "id": "c8bab16e",
"metadata": {},
"source": [
"In the side-by-side comparison we can see that the edges of, and lines on, the chequerboard have become straighter."
@@ -431,6 +465,7 @@
},
{
"cell_type": "markdown",
+ "id": "91bc7613",
"metadata": {},
"source": [
"Warping is a complex operation and is described in **Robotics, Vision & Control: Python**. For `image.warp[U,V]`, `U` and `V` are coordinate matrices as discussed above, and the output image will be the same size. For every pixel coordinate (u,v) in the output image, its location in the input image `image` is given by (U[v,u],V[v,u]). This is generally a non-integer coordinate so the pixel value is obtained by interpolation from `image`. Note that it's possible for (U[v,u],V[v,u]) to reference a pixel coordinate that lies outside the bounds of the image -- in this case the interpolated pixel is set to some special value, perhaps NaN or 0."
@@ -438,6 +473,7 @@
},
{
"cell_type": "markdown",
+ "id": "58163c2a",
"metadata": {},
"source": [
"Another way to visually represent the image distortion is to show how $(\\delta_u, \\delta_v)$ changes as a function of $(u,v)$"
@@ -446,6 +482,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "2344bfa4",
"metadata": {},
"outputs": [],
"source": [
@@ -455,6 +492,7 @@
},
{
"cell_type": "markdown",
+ "id": "28ce6e53",
"metadata": {},
"source": [
"which shows a pattern consistent with barrel distortion"
@@ -463,23 +501,14 @@
],
"metadata": {
"kernelspec": {
- "display_name": "dev",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.12.8"
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/camera.ipynb b/docs/notebooks/camera.ipynb
index e72d5240..d96b3979 100644
--- a/docs/notebooks/camera.ipynb
+++ b/docs/notebooks/camera.ipynb
@@ -2,6 +2,7 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "5084e76d",
"metadata": {
"id": "GOBPjUzoqL5j"
},
@@ -9,7 +10,7 @@
"\n",
" \n",
" Modeling a perspective camera | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -20,6 +21,7 @@
},
{
"cell_type": "markdown",
+ "id": "37d2a7ed",
"metadata": {
"id": "l-p9YGCUqRra"
},
@@ -31,106 +33,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
- "\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
"\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
"\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
"\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
- "\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -139,6 +138,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "97e8a887",
"metadata": {
"id": "NGGDoC29qR1a"
},
@@ -155,6 +155,7 @@
},
{
"cell_type": "markdown",
+ "id": "e8699d93",
"metadata": {
"id": "CNcehwNmqL5t"
},
@@ -169,6 +170,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "5ee1eb69",
"metadata": {
"id": "vAIz_xK9qL5u"
},
@@ -182,6 +184,7 @@
},
{
"cell_type": "markdown",
+ "id": "a1a65b97",
"metadata": {
"id": "ZNY-AQvCqL5u"
},
@@ -197,6 +200,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "df53822f",
"metadata": {
"id": "THUZYQIsqL5v"
},
@@ -210,6 +214,7 @@
},
{
"cell_type": "markdown",
+ "id": "cba399b9",
"metadata": {
"id": "pY0n-LzTqL5w"
},
@@ -220,6 +225,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "a7abbe5e",
"metadata": {
"id": "xYqu8FTkqL5w"
},
@@ -232,6 +238,7 @@
},
{
"cell_type": "markdown",
+ "id": "23c69f26",
"metadata": {
"id": "Mqfb7FI9qL5w"
},
@@ -242,6 +249,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "cf36c1ab",
"metadata": {
"id": "PvetB5hLqL5x"
},
@@ -252,6 +260,7 @@
},
{
"cell_type": "markdown",
+ "id": "2b012269",
"metadata": {
"id": "1TlYJip_qL5x"
},
@@ -262,6 +271,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "2e071334",
"metadata": {
"id": "FvypDqy7qL5y"
},
@@ -273,6 +283,7 @@
},
{
"cell_type": "markdown",
+ "id": "f545e257",
"metadata": {
"id": "OlbgLj9GqL51"
},
@@ -283,6 +294,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "4f1d2af0",
"metadata": {
"id": "BwFao9FHqL51"
},
@@ -294,6 +306,7 @@
},
{
"cell_type": "markdown",
+ "id": "a14c7cc5",
"metadata": {
"id": "-FIVXwtxqL52"
},
@@ -304,6 +317,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "d0f58d5f",
"metadata": {
"id": "ZF0DVhGXqL54"
},
@@ -314,6 +328,7 @@
},
{
"cell_type": "markdown",
+ "id": "98a4f9c9",
"metadata": {
"id": "OPzACappqL54"
},
@@ -324,6 +339,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "e0329ebe",
"metadata": {
"id": "BJWstKNDqL55"
},
@@ -334,6 +350,7 @@
},
{
"cell_type": "markdown",
+ "id": "ad8701d7",
"metadata": {
"id": "20aGjvi0qL55"
},
@@ -344,6 +361,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "b58f29ae",
"metadata": {
"id": "fec4Bj3NqL56"
},
@@ -354,6 +372,7 @@
},
{
"cell_type": "markdown",
+ "id": "75022795",
"metadata": {
"id": "HPUMGjz0qL56"
},
@@ -364,6 +383,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1e84c0df",
"metadata": {
"id": "kkVCgK8uqL56"
},
@@ -375,6 +395,7 @@
},
{
"cell_type": "markdown",
+ "id": "7b652bf0",
"metadata": {
"id": "Xl71ZCxkqL57"
},
@@ -387,6 +408,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "e5867564",
"metadata": {
"id": "iO-JWuPbqL57"
},
@@ -398,6 +420,7 @@
},
{
"cell_type": "markdown",
+ "id": "7e5af42d",
"metadata": {},
"source": [
"Then we recompute the _camera_ matrix and project our original point onto the image plane of the moved camera."
@@ -406,6 +429,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "fb10276d",
"metadata": {},
"outputs": [],
"source": [
@@ -415,6 +439,7 @@
},
{
"cell_type": "markdown",
+ "id": "eab5d609",
"metadata": {},
"source": [
"We see that the u-coordinate has decreased as we would expect - when we move our head to the right the world appears to move to the left."
@@ -422,6 +447,7 @@
},
{
"cell_type": "markdown",
+ "id": "016eb669",
"metadata": {
"id": "Sf9guXAwqL58"
},
@@ -432,6 +458,7 @@
},
{
"cell_type": "markdown",
+ "id": "260d16c1",
"metadata": {},
"source": [
"The toolbox provide a class to make this a bit more convenient. We have to provide the focal length `f`, pixel scale factor `rho`, the principal point `pp`, and the image dimensions `imagesize` (in this case 1000x1000)"
@@ -440,6 +467,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "86dcb3cc",
"metadata": {
"id": "2R2xF8sEqL58"
},
@@ -451,6 +479,7 @@
},
{
"cell_type": "markdown",
+ "id": "85d685ef",
"metadata": {
"id": "CKqgw5g9qL59"
},
@@ -461,6 +490,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "017702cc",
"metadata": {
"id": "_gpp59AHqL59"
},
@@ -471,6 +501,7 @@
},
{
"cell_type": "markdown",
+ "id": "ecd4247e",
"metadata": {
"id": "g3_Ua5prqL5-"
},
@@ -481,6 +512,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "a170e39d",
"metadata": {
"id": "ohx0aJvRqL5_"
},
@@ -491,6 +523,7 @@
},
{
"cell_type": "markdown",
+ "id": "93046656",
"metadata": {
"id": "R-zF3RX9qL6A"
},
@@ -501,6 +534,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "fa367fcc",
"metadata": {
"id": "PkMqgei-qL6B"
},
@@ -511,6 +545,7 @@
},
{
"cell_type": "markdown",
+ "id": "5525c08a",
"metadata": {
"id": "HN8vg4pDqL6D"
},
@@ -525,6 +560,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "9a4eb5bd",
"metadata": {
"id": "l8bKcrphqL6G"
},
@@ -535,6 +571,7 @@
},
{
"cell_type": "markdown",
+ "id": "f13bb385",
"metadata": {
"id": "m_9Kqb8jqL6H"
},
@@ -545,6 +582,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1a6278d8",
"metadata": {},
"outputs": [],
"source": [
@@ -553,6 +591,7 @@
},
{
"cell_type": "markdown",
+ "id": "862358b5",
"metadata": {},
"source": [
"and also the camera matrix for the case where the camera is moved"
@@ -561,6 +600,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "0113e94b",
"metadata": {
"id": "yJiJ1RVDqL6I"
},
@@ -571,57 +611,15 @@
}
],
"metadata": {
- "colab": {
- "name": "camera.ipynb",
- "provenance": []
- },
"kernelspec": {
- "display_name": "Python 3 (ipykernel)",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.13.11"
- },
- "varInspector": {
- "cols": {
- "lenName": 16,
- "lenType": 16,
- "lenVar": 40
- },
- "kernels_config": {
- "python": {
- "delete_cmd_postfix": "",
- "delete_cmd_prefix": "del ",
- "library": "var_list.py",
- "varRefreshCmd": "print(var_dic_list())"
- },
- "r": {
- "delete_cmd_postfix": ") ",
- "delete_cmd_prefix": "rm(",
- "library": "var_list.r",
- "varRefreshCmd": "cat(var_dic_list()) "
- }
- },
- "types_to_exclude": [
- "module",
- "function",
- "builtin_function_or_method",
- "instance",
- "_Feature"
- ],
- "window_display": false
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 4
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/camera_animation.ipynb b/docs/notebooks/camera_animation.ipynb
index ff6e9c2c..43c7c8b6 100644
--- a/docs/notebooks/camera_animation.ipynb
+++ b/docs/notebooks/camera_animation.ipynb
@@ -2,12 +2,13 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "e4abddd6",
"metadata": {},
"source": [
"\n",
" \n",
" Modeling a perspective camera | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -18,6 +19,7 @@
},
{
"cell_type": "markdown",
+ "id": "3be193a2",
"metadata": {},
"source": [
"## Configuring the Jupyter environment\n",
@@ -27,106 +29,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
- "\n",
- "\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
- "\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
- "\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
- "\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
+ "\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
+ "\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
+ "\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -135,6 +134,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "e5b96986",
"metadata": {},
"outputs": [],
"source": [
@@ -148,6 +148,7 @@
},
{
"cell_type": "markdown",
+ "id": "da360576",
"metadata": {},
"source": [
"***\n",
@@ -174,6 +175,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "65e94cf0",
"metadata": {},
"outputs": [],
"source": [
@@ -219,23 +221,14 @@
],
"metadata": {
"kernelspec": {
- "display_name": "RVSS",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.10.19"
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/clear_outputs.py b/docs/notebooks/clear_outputs.py
deleted file mode 100644
index a23f1d6e..00000000
--- a/docs/notebooks/clear_outputs.py
+++ /dev/null
@@ -1,100 +0,0 @@
-#!/usr/bin/env python
-"""Clear cell outputs and execution counts from every notebook in this folder.
-
-Pure stdlib (no dependency on jupyter/nbconvert being installed), so it can run as
-a commit hook on any machine with just Python. Equivalent to
-`jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace`, which is what
-clear_notebook_outputs.sh does for ad-hoc/manual use.
-
-Usage:
- python clear_outputs.py clear any notebook that has output
- python clear_outputs.py --check report only, exit 1 if anything has output
- python clear_outputs.py FILE ... only consider the given notebook(s)
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from pathlib import Path
-
-HERE = Path(__file__).resolve().parent
-
-
-def clear_cell(cell: dict) -> bool:
- """Clear one cell's outputs/execution count in place.
-
- :returns: True if the cell was (or would be) changed.
- """
- if cell.get("cell_type") != "code":
- return False
-
- changed = False
- if cell.get("outputs"):
- changed = True
- cell["outputs"] = []
- if cell.get("execution_count") is not None:
- changed = True
- cell["execution_count"] = None
- if "execution" in cell.get("metadata", {}):
- changed = True
- del cell["metadata"]["execution"]
-
- return changed
-
-
-def process_notebook(path: Path, fix: bool) -> bool:
- """Check (and optionally clear) one notebook's outputs.
-
- :returns: True if the notebook was (or would be) changed.
- """
- with path.open("r", encoding="utf-8") as f:
- nb = json.load(f)
-
- changed = any(clear_cell(cell) for cell in nb.get("cells", []))
-
- if changed and fix:
- with path.open("w", encoding="utf-8") as f:
- json.dump(nb, f, indent=1)
- f.write("\n")
-
- return changed
-
-
-def main() -> int:
- parser = argparse.ArgumentParser(description=__doc__)
- parser.add_argument(
- "--check",
- action="store_true",
- help="report notebooks with output without modifying them; exit 1 if any found",
- )
- parser.add_argument(
- "files",
- nargs="*",
- type=Path,
- help="only consider these notebooks (default: every *.ipynb in this folder)",
- )
- args = parser.parse_args()
-
- fix = not args.check
- notebooks = [p.resolve() for p in args.files] if args.files else sorted(HERE.glob("*.ipynb"))
-
- any_changed = False
- for nb_path in notebooks:
- changed = process_notebook(nb_path, fix=fix)
- if changed:
- any_changed = True
- rel = nb_path.relative_to(HERE.parent.parent)
- if fix:
- print(f"{rel}: found output, clearing it")
- else:
- print(f"{rel}: found output")
-
- if args.check and any_changed:
- return 1
- return 0
-
-
-if __name__ == "__main__":
- sys.exit(main())
diff --git a/docs/notebooks/color-images.ipynb b/docs/notebooks/color-images.ipynb
index 89121510..781d8b52 100644
--- a/docs/notebooks/color-images.ipynb
+++ b/docs/notebooks/color-images.ipynb
@@ -2,12 +2,13 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "90877b72",
"metadata": {},
"source": [
"\n",
" \n",
" Color images | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -18,6 +19,7 @@
},
{
"cell_type": "markdown",
+ "id": "79389825",
"metadata": {},
"source": [
"## Configuring the Jupyter environment\n",
@@ -27,106 +29,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
"\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
"\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
"\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
- "\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
- "\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -135,6 +134,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ea17abdb",
"metadata": {},
"outputs": [],
"source": [
@@ -154,6 +154,7 @@
},
{
"cell_type": "markdown",
+ "id": "57f9dd2e",
"metadata": {},
"source": [
"# Color images\n",
@@ -163,6 +164,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "6b4ff2dc",
"metadata": {},
"outputs": [],
"source": [
@@ -172,6 +174,7 @@
},
{
"cell_type": "markdown",
+ "id": "edf3efa9",
"metadata": {},
"source": [
"The size of the image is"
@@ -180,6 +183,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1df7027f",
"metadata": {},
"outputs": [],
"source": [
@@ -188,6 +192,7 @@
},
{
"cell_type": "markdown",
+ "id": "102aa771",
"metadata": {},
"source": [
"that is, it is 640x426.\n",
@@ -198,6 +203,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "61f16678",
"metadata": {},
"outputs": [],
"source": [
@@ -207,6 +213,7 @@
},
{
"cell_type": "markdown",
+ "id": "16919c3e",
"metadata": {},
"source": [
"which is simply a big 3-dimensional array of 8-bit integers. We can consider this as a stack of 2-dimensional tables each of shape (426,640) and we refer to these as color planes. The planes correspond to the colors red, green and blue, and the elements vary between 0 (zero amount of the corresponding color) and 255 (maximum amount of the corresponding color)."
@@ -214,6 +221,7 @@
},
{
"cell_type": "markdown",
+ "id": "4e332ac8",
"metadata": {},
"source": [
"To make this clearer, we can access the value of the pixel at image coordinate (516,351), remember that's (horizontal, vertical) coordinate"
@@ -222,6 +230,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "c98851b2",
"metadata": {},
"outputs": [],
"source": [
@@ -230,6 +239,7 @@
},
{
"cell_type": "markdown",
+ "id": "8dc1e626",
"metadata": {},
"source": [
"which is a 3-element 1-dimensional array with `uint8` values. This is the intensity of red, green and blue respectively.\n"
@@ -237,6 +247,7 @@
},
{
"cell_type": "markdown",
+ "id": "46ccd984",
"metadata": {},
"source": [
"\n",
@@ -245,6 +256,7 @@
},
{
"cell_type": "markdown",
+ "id": "c9049297",
"metadata": {},
"source": [
"\n",
@@ -253,6 +265,7 @@
},
{
"cell_type": "markdown",
+ "id": "686c22d1",
"metadata": {},
"source": [
"We can see a lot of pertinant information about the image by"
@@ -261,6 +274,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "b629e1e1",
"metadata": {},
"outputs": [],
"source": [
@@ -269,6 +283,7 @@
},
{
"cell_type": "markdown",
+ "id": "5f6e7419",
"metadata": {},
"source": [
"which says that the image contains 3 \"color planes\" named R, G and B, and each plane is 640x426.\n",
@@ -279,6 +294,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ec8b30ee",
"metadata": {},
"outputs": [],
"source": [
@@ -287,6 +303,7 @@
},
{
"cell_type": "markdown",
+ "id": "2880001f",
"metadata": {},
"source": [
"As we saw earlier, the image view is interactive. As you move the cursor over the image, the pixel coordinates and value are updated at the bottom of the window. The displayed pixel values are always in the range 0 to 255 which are minimum and maximum possible values for the `uint8` pixel data type.\n",
@@ -298,6 +315,7 @@
},
{
"cell_type": "markdown",
+ "id": "bee700fb",
"metadata": {},
"source": [
"**Q: move the cursor over the image and see the pixel values at the bottom right. Use the buttons with the square in it to select a region of interest (click the button, then click and drag a rectangle in the image window, the home button restores the original view). How do the pixel values vary as you explore different colored flowers? (there are some very small blue flowers)**"
@@ -305,6 +323,7 @@
},
{
"cell_type": "markdown",
+ "id": "cb89ab4b",
"metadata": {},
"source": [
"# Color planes\n",
@@ -314,6 +333,7 @@
},
{
"cell_type": "markdown",
+ "id": "9f3b1c2c",
"metadata": {},
"source": [
"Note that we can have images with 2, 3, 4 or more planes. Hyperspectral cameras can \"see\" uptp 20 colors (often called bands, short for spectral bands). The number of planes in the image is given by"
@@ -322,6 +342,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "6c128df2",
"metadata": {},
"outputs": [],
"source": [
@@ -330,6 +351,7 @@
},
{
"cell_type": "markdown",
+ "id": "e77aa0d5",
"metadata": {},
"source": [
"Some images might have 3 planes but they represent hue, saturation and intensity, rather than red, green and blue. The names of the planes, and which \"layer\" in the 3D-array they are in is given by "
@@ -338,6 +360,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1a2b3157",
"metadata": {},
"outputs": [],
"source": [
@@ -346,6 +369,7 @@
},
{
"cell_type": "markdown",
+ "id": "0d208d61",
"metadata": {},
"source": [
"\n",
@@ -355,6 +379,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "63e30b1f",
"metadata": {},
"outputs": [],
"source": [
@@ -364,6 +389,7 @@
},
{
"cell_type": "markdown",
+ "id": "95ea8b90",
"metadata": {},
"source": [
"and we see that is a greyscale image. The intensity of each pixel is the amount of red at the corresponding pixel in the original color image."
@@ -372,6 +398,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ccd521c4",
"metadata": {},
"outputs": [],
"source": [
@@ -380,6 +407,7 @@
},
{
"cell_type": "markdown",
+ "id": "6b26558d",
"metadata": {},
"source": [
"**Q: why are red flowers so dark in this image?**\n",
@@ -391,6 +419,7 @@
},
{
"cell_type": "markdown",
+ "id": "e4ab69db",
"metadata": {},
"source": [
"We could also have written `image.plane(0)`, `image.plane(\"R\")`, or `image[0]`."
@@ -398,6 +427,7 @@
},
{
"cell_type": "markdown",
+ "id": "afb3c279",
"metadata": {},
"source": [
"# Greyscale and color conversion\n",
@@ -408,6 +438,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "8788c2a8",
"metadata": {},
"outputs": [],
"source": [
@@ -416,6 +447,7 @@
},
{
"cell_type": "markdown",
+ "id": "6bd394cb",
"metadata": {},
"source": [
"where the greyscale value is a weighted average of the red, greend and blue values. The hightest weighting is for green and the lowest weighting is for blue, to match the response of the human eye."
@@ -423,6 +455,7 @@
},
{
"cell_type": "markdown",
+ "id": "0d761f7c",
"metadata": {},
"source": [
"We could also colorize the red plane image from above. Here we say that the red value is equal to the corresponding greyscale value, while green and blue are set to zero. The result is a color image, but the only color is red."
@@ -431,6 +464,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "3f7041d4",
"metadata": {},
"outputs": [],
"source": [
@@ -439,6 +473,7 @@
},
{
"cell_type": "markdown",
+ "id": "0d2320f9",
"metadata": {},
"source": [
"# Histograms\n",
@@ -449,6 +484,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "78ad3417",
"metadata": {},
"outputs": [],
"source": [
@@ -457,6 +493,7 @@
},
{
"cell_type": "markdown",
+ "id": "ca985983",
"metadata": {},
"source": [
"which shows that the pixels span the full range from 0 to 255. A histogram provides more nuanced information"
@@ -465,6 +502,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "a3e35c61",
"metadata": {},
"outputs": [],
"source": [
@@ -475,6 +513,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "626e7574",
"metadata": {},
"outputs": [],
"source": [
@@ -484,6 +523,7 @@
},
{
"cell_type": "markdown",
+ "id": "67a7718e",
"metadata": {},
"source": [
"We see that the blue channel has a large number of 0 values. We also see that all channels are overexposed, a large number of pixels have the maximum value of 255.\n",
@@ -496,65 +536,14 @@
],
"metadata": {
"kernelspec": {
- "display_name": "dev",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.12.8"
- },
- "toc": {
- "base_numbering": 1,
- "nav_menu": {},
- "number_sections": true,
- "sideBar": true,
- "skip_h1_title": false,
- "title_cell": "Table of Contents",
- "title_sidebar": "Contents",
- "toc_cell": false,
- "toc_position": {},
- "toc_section_display": true,
- "toc_window_display": false
- },
- "varInspector": {
- "cols": {
- "lenName": 16,
- "lenType": 16,
- "lenVar": 40
- },
- "kernels_config": {
- "python": {
- "delete_cmd_postfix": "",
- "delete_cmd_prefix": "del ",
- "library": "var_list.py",
- "varRefreshCmd": "print(var_dic_list())"
- },
- "r": {
- "delete_cmd_postfix": ") ",
- "delete_cmd_prefix": "rm(",
- "library": "var_list.r",
- "varRefreshCmd": "cat(var_dic_list()) "
- }
- },
- "types_to_exclude": [
- "module",
- "function",
- "builtin_function_or_method",
- "instance",
- "_Feature"
- ],
- "window_display": false
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/exploring-images.ipynb b/docs/notebooks/exploring-images.ipynb
index acff577b..5fa1f3f4 100644
--- a/docs/notebooks/exploring-images.ipynb
+++ b/docs/notebooks/exploring-images.ipynb
@@ -2,12 +2,13 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "1caad4ac",
"metadata": {},
"source": [
"\n",
" \n",
" Exploring images and pixels | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -18,6 +19,7 @@
},
{
"cell_type": "markdown",
+ "id": "dae40f36",
"metadata": {},
"source": [
"Set matplotlib for interactive display within the notebook, then import the `Image` object from the Machine Vision Toolbox."
@@ -25,106 +27,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
- "\n",
- "\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
"\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
"\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
"\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -133,6 +132,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "44625a7a",
"metadata": {},
"outputs": [],
"source": [
@@ -142,6 +142,7 @@
},
{
"cell_type": "markdown",
+ "id": "21d7d82d",
"metadata": {},
"source": [
"# The `Image` class\n",
@@ -152,6 +153,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "b50a7f6d",
"metadata": {},
"outputs": [],
"source": [
@@ -160,6 +162,7 @@
},
{
"cell_type": "markdown",
+ "id": "782f25d9",
"metadata": {},
"source": [
"The `mono` option means don't convert it to greyscale, though after you've worked through the notebook, it would be interesting to rerun with this option set to `True`.\n",
@@ -170,6 +173,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "812bc00d",
"metadata": {},
"outputs": [],
"source": [
@@ -178,6 +182,7 @@
},
{
"cell_type": "markdown",
+ "id": "24975f8f",
"metadata": {},
"source": [
"that contains the color image and has many methods to operate on the image.\n",
@@ -188,6 +193,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "59389b7e",
"metadata": {},
"outputs": [],
"source": [
@@ -196,6 +202,7 @@
},
{
"cell_type": "markdown",
+ "id": "6d4b1a0a",
"metadata": {},
"source": [
"As you move the cursor around, the cursor location and the pixel values are updated beneath the image. Note that the pixel value is a 3-vector whose elements are the amount of red (R), green (G) and blue (B) at that point. \n",
@@ -207,6 +214,7 @@
},
{
"cell_type": "markdown",
+ "id": "5ef7d075",
"metadata": {},
"source": [
"The size of the image is usually described in terms of width x height"
@@ -215,6 +223,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "9feb7b2b",
"metadata": {},
"outputs": [],
"source": [
@@ -223,6 +232,7 @@
},
{
"cell_type": "markdown",
+ "id": "3da29820",
"metadata": {},
"source": [
"and the individual pixel values have a datatype"
@@ -231,6 +241,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ec49e015",
"metadata": {},
"outputs": [],
"source": [
@@ -239,6 +250,7 @@
},
{
"cell_type": "markdown",
+ "id": "e8648386",
"metadata": {},
"source": [
"which in this case in unsigned 8-bit integer. Their range can be determined by"
@@ -247,6 +259,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "6fa08d2c",
"metadata": {},
"outputs": [],
"source": [
@@ -255,6 +268,7 @@
},
{
"cell_type": "markdown",
+ "id": "a2c8291a",
"metadata": {},
"source": [
"The image comprises"
@@ -263,6 +277,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "410b4688",
"metadata": {},
"outputs": [],
"source": [
@@ -271,6 +286,7 @@
},
{
"cell_type": "markdown",
+ "id": "d9d7f844",
"metadata": {},
"source": [
"\"planes\" that hold the red, green and blue values respectively."
@@ -278,6 +294,7 @@
},
{
"cell_type": "markdown",
+ "id": "b43afebe",
"metadata": {},
"source": [
"All of this metadata about the image can be seen by displaying the value of the `Image` instance, "
@@ -286,6 +303,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "5c6b3f1a",
"metadata": {},
"outputs": [],
"source": [
@@ -294,6 +312,7 @@
},
{
"cell_type": "markdown",
+ "id": "7df03051",
"metadata": {},
"source": [
"you don't see all the pixel values, just the key properties. Many other properties can be accessed as attributes or properties of the instance."
@@ -301,6 +320,7 @@
},
{
"cell_type": "markdown",
+ "id": "ce78fab5",
"metadata": {},
"source": [
"# Color planes\n",
@@ -313,6 +333,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "309d1279",
"metadata": {},
"outputs": [],
"source": [
@@ -322,6 +343,7 @@
},
{
"cell_type": "markdown",
+ "id": "1c001224",
"metadata": {},
"source": [
"Note that the resulting \"green plane\" is another `Image` instance, but this time it has only"
@@ -330,6 +352,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "731c166d",
"metadata": {},
"outputs": [],
"source": [
@@ -338,6 +361,7 @@
},
{
"cell_type": "markdown",
+ "id": "2f68fc4c",
"metadata": {},
"source": [
"plane, it is a greyscale image. It is easy to display"
@@ -346,6 +370,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "d6e84bdf",
"metadata": {},
"outputs": [],
"source": [
@@ -354,6 +379,7 @@
},
{
"cell_type": "markdown",
+ "id": "d6110477",
"metadata": {},
"source": [
"and we see that the white flowers appear bright, they have a strong green component, as do the leaves, but the red flowers appear very dark, they have little green."
@@ -361,6 +387,7 @@
},
{
"cell_type": "markdown",
+ "id": "28a06ba6",
"metadata": {},
"source": [
"The `Image` object supports an arbitrary number of planes in any order. The `colororder` dict "
@@ -369,6 +396,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "d00760e0",
"metadata": {},
"outputs": [],
"source": [
@@ -377,6 +405,7 @@
},
{
"cell_type": "markdown",
+ "id": "c82f8e4e",
"metadata": {},
"source": [
"is a mapping from colorplane name to the plane index. The example above we could also have done as"
@@ -385,6 +414,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "c80d0630",
"metadata": {},
"outputs": [],
"source": [
@@ -393,6 +423,7 @@
},
{
"cell_type": "markdown",
+ "id": "00e5df01",
"metadata": {},
"source": [
"since the green plane, in this case has a plane index of 1. However the RGB order is just a convention, and we shouldn't rely on assuming that the green plane is always index 1."
@@ -400,6 +431,7 @@
},
{
"cell_type": "markdown",
+ "id": "b8c1458f",
"metadata": {},
"source": [
"The actual distribution of the pixel values in each plane is"
@@ -408,6 +440,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "cde38f5c",
"metadata": {},
"outputs": [],
"source": [
@@ -416,6 +449,7 @@
},
{
"cell_type": "markdown",
+ "id": "619ba851",
"metadata": {},
"source": [
"which shows that the red, green and blue values all vary from 0 to 255, the maximum permissible range. This is unusual, but the white flowers have pushed each of the color channels to the limit.\n",
@@ -426,6 +460,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "aee0ba6e",
"metadata": {},
"outputs": [],
"source": [
@@ -434,6 +469,7 @@
},
{
"cell_type": "markdown",
+ "id": "76511af3",
"metadata": {},
"source": [
"the comparison creates an `Image` instance with boolean values, true where the pixel value is zero. The `disp()` method displays `True` as white, and we can see a few white pixels in the lower left of the image.\n",
@@ -443,6 +479,7 @@
},
{
"cell_type": "markdown",
+ "id": "60cc6249",
"metadata": {},
"source": [
"The value at a particular coordinate (280,220) in the image is given by"
@@ -451,6 +488,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "001a365c",
"metadata": {},
"outputs": [],
"source": [
@@ -459,6 +497,7 @@
},
{
"cell_type": "markdown",
+ "id": "c2fa0169",
"metadata": {},
"source": [
"and we see the result is a 3-vector, as a 1d Numpy array. This is the amount of red, green and blue at that particular point. Red dominates in this case because the point belongs to one of the red flowers."
@@ -466,6 +505,7 @@
},
{
"cell_type": "markdown",
+ "id": "64f839f7",
"metadata": {},
"source": [
"We can also grab a subregion of the image using Python slice notation"
@@ -474,6 +514,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "f369f1f4",
"metadata": {},
"outputs": [],
"source": [
@@ -483,6 +524,7 @@
},
{
"cell_type": "markdown",
+ "id": "7bdffd48",
"metadata": {},
"source": [
"and the result is now another `Image` instance which we can display"
@@ -491,6 +533,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "b54c27de",
"metadata": {},
"outputs": [],
"source": [
@@ -499,6 +542,7 @@
},
{
"cell_type": "markdown",
+ "id": "4385e648",
"metadata": {},
"source": [
"and it is the elusive blue flower!"
@@ -506,6 +550,7 @@
},
{
"cell_type": "markdown",
+ "id": "53e9caf4",
"metadata": {},
"source": [
"The pixel data is actually held in a Numpy array encapsulated by the `Image` object. We can access it"
@@ -514,6 +559,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "d0d00fcb",
"metadata": {},
"outputs": [],
"source": [
@@ -523,6 +569,7 @@
},
{
"cell_type": "markdown",
+ "id": "dcdaeefc",
"metadata": {},
"source": [
"and see that it is indeed a Numpy array. Its shape"
@@ -531,6 +578,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "3439cff1",
"metadata": {},
"outputs": [],
"source": [
@@ -539,6 +587,7 @@
},
{
"cell_type": "markdown",
+ "id": "aa37b12e",
"metadata": {},
"source": [
"is given as the number of rows (height), columns (width) and planes. Compare these numbers with the properties of the `Image` instance shown above.\n",
@@ -549,6 +598,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "32c37aba",
"metadata": {},
"outputs": [],
"source": [
@@ -557,6 +607,7 @@
},
{
"cell_type": "markdown",
+ "id": "5a0cc5c8",
"metadata": {},
"source": [
"but note that we have had to swap the indices. Numpy coordinates are given in column, row order, whereas the `Image` instance supports the image coordinate system convention of column then row."
@@ -564,6 +615,7 @@
},
{
"cell_type": "markdown",
+ "id": "1f8bdb3b",
"metadata": {},
"source": [
"Repeat this notebook, with `mono` set to `True` in the second cell. Note the differences."
@@ -572,6 +624,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "cb8b581c",
"metadata": {},
"outputs": [],
"source": []
@@ -579,23 +632,14 @@
],
"metadata": {
"kernelspec": {
- "display_name": "dev",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.12.8"
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/fiducials.ipynb b/docs/notebooks/fiducials.ipynb
index b57cda4a..0c7a3e31 100644
--- a/docs/notebooks/fiducials.ipynb
+++ b/docs/notebooks/fiducials.ipynb
@@ -2,13 +2,14 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "d7b7fd69",
"metadata": {
"id": "98tzSzdEfn-5"
},
"source": [
"\n",
" \n",
- "  | \n",
+ "  | \n",
" Finding fiducial markers | \n",
"
\n",
"
\n",
@@ -20,6 +21,7 @@
},
{
"cell_type": "markdown",
+ "id": "5120a0c6",
"metadata": {
"id": "o08yYqLXfsd_"
},
@@ -31,106 +33,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
"\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
"\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
"\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
- "\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
- "\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -139,6 +138,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "90127a27",
"metadata": {
"id": "WkfRfV6bfspV"
},
@@ -157,6 +157,7 @@
},
{
"cell_type": "markdown",
+ "id": "eb720781",
"metadata": {
"id": "3hSqz-Rifn-7"
},
@@ -177,6 +178,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "853b4f42",
"metadata": {
"id": "yYJ8OOUmfn-7"
},
@@ -189,6 +191,7 @@
},
{
"cell_type": "markdown",
+ "id": "08acc339",
"metadata": {
"id": "CBydI3Iifn-8"
},
@@ -197,7 +200,7 @@
"- the focal length, in this case 4.25mm\n",
"- the image size\n",
"- the principal point, where the optical axis passes through the image plane\n",
- "- the pixel size, in this case 1.4\u03bcm\n",
+ "- the pixel size, in this case 1.4μm\n",
"\n",
"From the camera model we can derive the intrinsic parameter matrix"
]
@@ -205,6 +208,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1a5d60df",
"metadata": {
"id": "BeqUEfOpfn-8"
},
@@ -216,6 +220,7 @@
},
{
"cell_type": "markdown",
+ "id": "54fa9b52",
"metadata": {
"id": "WCuDwrf3fn-9"
},
@@ -226,6 +231,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "281ffe0d",
"metadata": {
"id": "DEqJDV3qfn-9"
},
@@ -236,6 +242,7 @@
},
{
"cell_type": "markdown",
+ "id": "3d13c2a9",
"metadata": {
"id": "vCcamFjqfn-9"
},
@@ -246,6 +253,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "8e23c970",
"metadata": {
"id": "CCCAF8q-fn-9"
},
@@ -257,6 +265,7 @@
},
{
"cell_type": "markdown",
+ "id": "1ab4ff26",
"metadata": {
"id": "Pk3y8-IBfn--"
},
@@ -267,6 +276,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "3525aeb0",
"metadata": {
"id": "1zFXNPHOfn--"
},
@@ -277,6 +287,7 @@
},
{
"cell_type": "markdown",
+ "id": "d33bce94",
"metadata": {
"id": "RSa1p9m-fn-_"
},
@@ -287,6 +298,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "bab9e2c2",
"metadata": {
"id": "ZysRfRsnfn-_"
},
@@ -300,6 +312,7 @@
},
{
"cell_type": "markdown",
+ "id": "2727cf11",
"metadata": {
"id": "8Sgq_Gd9fn-_"
},
@@ -310,6 +323,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "af7025e5",
"metadata": {
"id": "3f00OESOfn_A"
},
@@ -320,6 +334,7 @@
},
{
"cell_type": "markdown",
+ "id": "cffebe58",
"metadata": {
"id": "s2XZz30pfn_A"
},
@@ -330,6 +345,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "497b856d",
"metadata": {
"id": "nihc3SySfn_A"
},
@@ -343,6 +359,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "bfb39ec1",
"metadata": {
"id": "hL0hbJmv9t6k"
},
@@ -351,57 +368,15 @@
}
],
"metadata": {
- "colab": {
- "name": "fiducuals.ipynb",
- "provenance": []
- },
"kernelspec": {
- "display_name": "dev",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.12.8"
- },
- "varInspector": {
- "cols": {
- "lenName": 16,
- "lenType": 16,
- "lenVar": 40
- },
- "kernels_config": {
- "python": {
- "delete_cmd_postfix": "",
- "delete_cmd_prefix": "del ",
- "library": "var_list.py",
- "varRefreshCmd": "print(var_dic_list())"
- },
- "r": {
- "delete_cmd_postfix": ") ",
- "delete_cmd_prefix": "rm(",
- "library": "var_list.r",
- "varRefreshCmd": "cat(var_dic_list()) "
- }
- },
- "types_to_exclude": [
- "module",
- "function",
- "builtin_function_or_method",
- "instance",
- "_Feature"
- ],
- "window_display": false
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 0
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/finding-blobs.ipynb b/docs/notebooks/finding-blobs.ipynb
index db6090cf..13be5a31 100644
--- a/docs/notebooks/finding-blobs.ipynb
+++ b/docs/notebooks/finding-blobs.ipynb
@@ -2,6 +2,7 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "6fd3900f",
"metadata": {
"id": "3LAph1JQd853"
},
@@ -9,7 +10,7 @@
"\n",
" \n",
" Finding blobs | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -20,6 +21,7 @@
},
{
"cell_type": "markdown",
+ "id": "b96adefb",
"metadata": {
"id": "9cvpuJXed856"
},
@@ -31,106 +33,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
"\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
"\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
"\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
- "\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
- "\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -139,6 +138,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "c49b5976",
"metadata": {
"id": "hZVsTop7d857"
},
@@ -162,6 +162,7 @@
},
{
"cell_type": "markdown",
+ "id": "acd016a9",
"metadata": {
"id": "I4sc5wwad858"
},
@@ -176,6 +177,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "57d44ed5",
"metadata": {
"id": "pB2NVnzRd859"
},
@@ -187,6 +189,7 @@
},
{
"cell_type": "markdown",
+ "id": "c324cdd6",
"metadata": {
"id": "dcEbN213d859"
},
@@ -202,6 +205,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "cda42bde",
"metadata": {
"id": "aB09CIFNd859"
},
@@ -212,6 +216,7 @@
},
{
"cell_type": "markdown",
+ "id": "1452a257",
"metadata": {
"id": "AeceeIFdd85-"
},
@@ -223,6 +228,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "84a6b5f4",
"metadata": {},
"outputs": [],
"source": [
@@ -231,6 +237,7 @@
},
{
"cell_type": "markdown",
+ "id": "7609496d",
"metadata": {},
"source": [
"Each blob has a number of properties which are shown in the columns of the table. Each blob has a unique `id` and a `parent` which will discuss later.\n",
@@ -241,6 +248,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "fec10d5e",
"metadata": {},
"outputs": [],
"source": [
@@ -250,6 +258,7 @@
},
{
"cell_type": "markdown",
+ "id": "b3bb168d",
"metadata": {
"id": "4oO51wxbd85-"
},
@@ -259,6 +268,7 @@
},
{
"cell_type": "markdown",
+ "id": "e96c0bf1",
"metadata": {
"id": "7E17CbbXd85_"
},
@@ -269,6 +279,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "c80d1405",
"metadata": {
"id": "vYMwsTvld85_"
},
@@ -279,6 +290,7 @@
},
{
"cell_type": "markdown",
+ "id": "46267c2f",
"metadata": {
"id": "1bYwIT0Ld85_"
},
@@ -289,6 +301,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "f767a05d",
"metadata": {
"id": "ia0GlwROd86A"
},
@@ -299,6 +312,7 @@
},
{
"cell_type": "markdown",
+ "id": "60ad1939",
"metadata": {
"id": "PtfHS3ktd86A"
},
@@ -309,6 +323,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "4614aa9e",
"metadata": {
"id": "ZnF0N-FAd86A"
},
@@ -319,6 +334,7 @@
},
{
"cell_type": "markdown",
+ "id": "9430b65d",
"metadata": {
"id": "gQKtyCZqd86A"
},
@@ -328,6 +344,7 @@
},
{
"cell_type": "markdown",
+ "id": "1065e8f2",
"metadata": {},
"source": [
"For each blob we can obtain the length of its perimeter"
@@ -336,6 +353,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1e50723d",
"metadata": {},
"outputs": [],
"source": [
@@ -344,6 +362,7 @@
},
{
"cell_type": "markdown",
+ "id": "4a836033",
"metadata": {},
"source": [
"as well as the perimeter, as a set of points"
@@ -352,6 +371,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "de9bef13",
"metadata": {},
"outputs": [],
"source": [
@@ -360,6 +380,7 @@
},
{
"cell_type": "markdown",
+ "id": "218c4b7c",
"metadata": {},
"source": [
"A simple but useful measure of \"shape\" is circularity, computed from area and perimeter. It is 1 for a circle and 0 for a line."
@@ -368,6 +389,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "e4a994df",
"metadata": {},
"outputs": [],
"source": [
@@ -376,6 +398,7 @@
},
{
"cell_type": "markdown",
+ "id": "27bb8aa0",
"metadata": {},
"source": [
"These properties can also be computed on a list of blob objects, and the result is an array or list. For example"
@@ -384,6 +407,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "bd8206a2",
"metadata": {},
"outputs": [],
"source": [
@@ -393,6 +417,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "8e535e64",
"metadata": {},
"outputs": [],
"source": [
@@ -401,6 +426,7 @@
},
{
"cell_type": "markdown",
+ "id": "8f331e6b",
"metadata": {
"id": "YqtDE9X6d86B"
},
@@ -412,6 +438,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "bee90751",
"metadata": {
"id": "v4EKdDcyd86B"
},
@@ -424,6 +451,7 @@
},
{
"cell_type": "markdown",
+ "id": "ab9e8576",
"metadata": {
"id": "sdnL_-Dhd86C"
},
@@ -434,6 +462,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "8f8f02b8",
"metadata": {
"id": "gX6UFF9zd86C"
},
@@ -445,6 +474,7 @@
},
{
"cell_type": "markdown",
+ "id": "e78c6e0c",
"metadata": {
"id": "T66pjgYOd86C"
},
@@ -457,6 +487,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "2aaad6b4",
"metadata": {
"id": "lDMd2dsEd86C"
},
@@ -468,6 +499,7 @@
},
{
"cell_type": "markdown",
+ "id": "02e923ef",
"metadata": {},
"source": [
"and display the parameters as a table"
@@ -476,6 +508,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "6760856c",
"metadata": {
"id": "32_Hmypyd86D"
},
@@ -486,6 +519,7 @@
},
{
"cell_type": "markdown",
+ "id": "7b7cc176",
"metadata": {
"id": "jh9fbZHJd86D"
},
@@ -498,6 +532,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "6d487f8c",
"metadata": {
"id": "ViPOvlVPd86D"
},
@@ -508,6 +543,7 @@
},
{
"cell_type": "markdown",
+ "id": "355e190a",
"metadata": {},
"source": [
"And the children of blob 2 are"
@@ -516,6 +552,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "f025e152",
"metadata": {
"id": "2lerQOFsd86D"
},
@@ -526,6 +563,7 @@
},
{
"cell_type": "markdown",
+ "id": "8b660a15",
"metadata": {},
"source": [
"The datastructure we need to represent this hierarchy is a tree. If you have the `graphviz` package installed and the `dot` command-line utility then we can run"
@@ -534,6 +572,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "6a8f25e8",
"metadata": {},
"outputs": [],
"source": [
@@ -542,6 +581,7 @@
},
{
"cell_type": "markdown",
+ "id": "56c592b6",
"metadata": {},
"source": [
"The final thing we will do is to create a label image and display it"
@@ -550,6 +590,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "e66cf602",
"metadata": {},
"outputs": [],
"source": [
@@ -564,6 +605,7 @@
},
{
"cell_type": "markdown",
+ "id": "2d7b88d5",
"metadata": {},
"source": [
"Where the value of each pixel is the `id` of the blob it belongs to. By drifting the cursor over the image you can see which pixels belong to say blob #6. The image uses a colorful colormap to make it easy to see the different label areas."
@@ -571,57 +613,15 @@
}
],
"metadata": {
- "colab": {
- "name": "finding-blobs.ipynb",
- "provenance": []
- },
"kernelspec": {
- "display_name": "dev",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.10.16"
- },
- "varInspector": {
- "cols": {
- "lenName": 16,
- "lenType": 16,
- "lenVar": 40
- },
- "kernels_config": {
- "python": {
- "delete_cmd_postfix": "",
- "delete_cmd_prefix": "del ",
- "library": "var_list.py",
- "varRefreshCmd": "print(var_dic_list())"
- },
- "r": {
- "delete_cmd_postfix": ") ",
- "delete_cmd_prefix": "rm(",
- "library": "var_list.r",
- "varRefreshCmd": "cat(var_dic_list()) "
- }
- },
- "types_to_exclude": [
- "module",
- "function",
- "builtin_function_or_method",
- "instance",
- "_Feature"
- ],
- "window_display": false
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 0
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/gamma.ipynb b/docs/notebooks/gamma.ipynb
index 9c8becb8..4cc310cc 100644
--- a/docs/notebooks/gamma.ipynb
+++ b/docs/notebooks/gamma.ipynb
@@ -2,12 +2,13 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "2afdd548",
"metadata": {},
"source": [
"\n",
" \n",
" Gamma encoding | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -18,6 +19,7 @@
},
{
"cell_type": "markdown",
+ "id": "2c353555",
"metadata": {},
"source": [
"## Configuring the Jupyter environment\n",
@@ -27,106 +29,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
- "\n",
- "\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
- "\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
- "\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
- "\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
+ "\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
+ "\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
+ "\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -135,6 +134,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "f041f9ae",
"metadata": {},
"outputs": [],
"source": [
@@ -153,6 +153,7 @@
},
{
"cell_type": "markdown",
+ "id": "d57b1b6a",
"metadata": {},
"source": [
"# Gamma\n",
@@ -163,6 +164,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "5bfd8eb7",
"metadata": {},
"outputs": [],
"source": [
@@ -172,6 +174,7 @@
},
{
"cell_type": "markdown",
+ "id": "d02e3284",
"metadata": {},
"source": [
"Explore the pixel values with the cursor. The third bar has twice the pixel value of the second bar but it doesn't appear this way. The last bar has twice the pixel value of the second last bar -- again the intensitites on the screen don't reflect that.\n",
@@ -184,6 +187,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "b4a13031",
"metadata": {},
"outputs": [],
"source": [
@@ -192,6 +196,7 @@
},
{
"cell_type": "markdown",
+ "id": "3b1005f2",
"metadata": {},
"source": [
"We see that the brightness steps now seem much more linear. This is only an approximation of the required gamma decoding but it shows the monitor non-linearity very clearly.\n",
@@ -202,23 +207,14 @@
],
"metadata": {
"kernelspec": {
- "display_name": "dev",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.10.16"
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/greyscale-images.ipynb b/docs/notebooks/greyscale-images.ipynb
index 158cdd3f..067b2aa6 100644
--- a/docs/notebooks/greyscale-images.ipynb
+++ b/docs/notebooks/greyscale-images.ipynb
@@ -2,12 +2,13 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "1b91caa9",
"metadata": {},
"source": [
"\n",
" \n",
" Greyscale images | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -18,6 +19,7 @@
},
{
"cell_type": "markdown",
+ "id": "6808c4c2",
"metadata": {},
"source": [
"## Configuring the Jupyter environment\n",
@@ -27,106 +29,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
- "\n",
- "\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
- "\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
- "\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
- "\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
+ "\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
+ "\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
+ "\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -135,6 +134,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "3d6ce74e",
"metadata": {},
"outputs": [],
"source": [
@@ -154,6 +154,7 @@
},
{
"cell_type": "markdown",
+ "id": "8c442b90",
"metadata": {},
"source": [
"# Create an image from data\n",
@@ -164,6 +165,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "8afa65de",
"metadata": {},
"outputs": [],
"source": [
@@ -176,6 +178,7 @@
},
{
"cell_type": "markdown",
+ "id": "3dd4d963",
"metadata": {},
"source": [
"We can see some kind of pattern in here, but it's much more obvious if we display this matrix as an image -- each element of the matrix corresponds to a pixel."
@@ -184,6 +187,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "25cffa77",
"metadata": {},
"outputs": [],
"source": [
@@ -193,6 +197,7 @@
},
{
"cell_type": "markdown",
+ "id": "963f7f28",
"metadata": {},
"source": [
"Now we can clearly see the pattern -- a face. We can see the equivalence between a 2D NumPy array and an image. The colors, magenta and yellow, are not part of the image, they are just the default behaviour of MatPlotLib's `imshow` method. As you drift the cursor over the image the pixel coordinates and pixel values are displayed beneath the image."
@@ -200,6 +205,7 @@
},
{
"cell_type": "markdown",
+ "id": "31ec5aa4",
"metadata": {},
"source": [
"We can also display this 2D array using the Machine Vision Toolbox for Python"
@@ -208,6 +214,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "0929113a",
"metadata": {},
"outputs": [],
"source": [
@@ -217,6 +224,7 @@
},
{
"cell_type": "markdown",
+ "id": "2a731289",
"metadata": {},
"source": [
"and the result is much the same, except the colors are now just black and white. It's a common convention that zero-valued pixels are displayed as black. `idisp` has scaled the values in the array so that the biggest value, 1, is displayed as brightest white.\n",
@@ -228,6 +236,7 @@
},
{
"cell_type": "markdown",
+ "id": "6a78b764",
"metadata": {},
"source": [
"# Working with a real image file\n"
@@ -235,6 +244,7 @@
},
{
"cell_type": "markdown",
+ "id": "a48b5f9d",
"metadata": {},
"source": [
"**In this section we will consider grey scale or monochrome images. Have a look at the color-images.ipynb notebook in this folder.**\n",
@@ -247,6 +257,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "f5e76d1f",
"metadata": {},
"outputs": [],
"source": [
@@ -257,6 +268,7 @@
},
{
"cell_type": "markdown",
+ "id": "ec227a6c",
"metadata": {},
"source": [
"`image` is an object that contains an image, the pixel data is contained in an internal NumPy array (a python style matrix) with dimensions"
@@ -265,6 +277,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "97eb8ce1",
"metadata": {},
"outputs": [],
"source": [
@@ -273,6 +286,7 @@
},
{
"cell_type": "markdown",
+ "id": "54bf0511",
"metadata": {},
"source": [
"which we see has 851 columns and 1280 rows (remember NumPy always has rows as the first index).\n",
@@ -282,6 +296,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "f972d3ab",
"metadata": {},
"outputs": [],
"source": [
@@ -291,6 +306,7 @@
},
{
"cell_type": "markdown",
+ "id": "6c0a1132",
"metadata": {},
"source": [
"is simply a big 2-dimensional table of 8-bit integers which represent brightness of each pixel as a number between 0 (black) and 255 (white)."
@@ -298,6 +314,7 @@
},
{
"cell_type": "markdown",
+ "id": "8b4c3068",
"metadata": {},
"source": [
"We can access the value of the pixel at image coordinate (100,200), remember that's (horizontal, vertical) coordinate"
@@ -306,6 +323,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "9571ab03",
"metadata": {},
"outputs": [],
"source": [
@@ -314,6 +332,7 @@
},
{
"cell_type": "markdown",
+ "id": "eb943107",
"metadata": {},
"source": [
"which we see is a `uint8` datatype of value 188."
@@ -321,6 +340,7 @@
},
{
"cell_type": "markdown",
+ "id": "877d7784",
"metadata": {},
"source": [
"However if we index the underlying NumPy array the same way"
@@ -329,6 +349,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1a1dc4e2",
"metadata": {},
"outputs": [],
"source": [
@@ -337,6 +358,7 @@
},
{
"cell_type": "markdown",
+ "id": "8141c0d1",
"metadata": {},
"source": [
"we get a different result. That's because for NumPy indexing the first index is the row, the second index is the column.\n",
@@ -347,6 +369,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "641a69dd",
"metadata": {},
"outputs": [],
"source": [
@@ -355,6 +378,7 @@
},
{
"cell_type": "markdown",
+ "id": "e15a81ff",
"metadata": {},
"source": [
"**This is a bit of a trap for those starting out doing image processing with NumPy** The MachineVision Toolbox is concerned with image processing so it strictly uses image coordinate indexing order."
@@ -362,6 +386,7 @@
},
{
"cell_type": "markdown",
+ "id": "190eeaad",
"metadata": {},
"source": [
"\n",
@@ -371,6 +396,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1d3d9cb7",
"metadata": {},
"outputs": [],
"source": [
@@ -379,6 +405,7 @@
},
{
"cell_type": "markdown",
+ "id": "7638f877",
"metadata": {},
"source": [
"\n",
@@ -388,6 +415,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "b23999da",
"metadata": {},
"outputs": [],
"source": [
@@ -396,6 +424,7 @@
},
{
"cell_type": "markdown",
+ "id": "81fdf366",
"metadata": {},
"source": [
"As we saw earlier, the notebook image view is interactive. As you move the cursor over the image, the pixel coordinates and value are updated at the bottom of the window. The displayed pixel values are always in the range 0 to 255 which are minimum and maximum possible values for the `uint8` pixel data type.\n",
@@ -405,6 +434,7 @@
},
{
"cell_type": "markdown",
+ "id": "9ce781dc",
"metadata": {},
"source": [
"**Q:**\n",
@@ -416,6 +446,7 @@
},
{
"cell_type": "markdown",
+ "id": "c768f007",
"metadata": {},
"source": [
"# Histograms\n",
@@ -426,6 +457,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "a48cb216",
"metadata": {},
"outputs": [],
"source": [
@@ -435,6 +467,7 @@
},
{
"cell_type": "markdown",
+ "id": "42b49486",
"metadata": {},
"source": [
"Which is an instance of a `Histogram` object that contains statistics about the pixel values in the image. We can plot the histogram using its `plot` method."
@@ -443,6 +476,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "08ec1b22",
"metadata": {},
"outputs": [],
"source": [
@@ -452,6 +486,7 @@
},
{
"cell_type": "markdown",
+ "id": "d36563a3",
"metadata": {},
"source": [
"We can see that the histogram is pretty ragged with three dominant peaks. Explore the image with the cursor and see which parts of the image correspond to these different peaks.\n",
@@ -462,6 +497,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "bedd7c84",
"metadata": {},
"outputs": [],
"source": [
@@ -471,6 +507,7 @@
},
{
"cell_type": "markdown",
+ "id": "e52fc357",
"metadata": {},
"source": [
"From this we can see that around 64% of pixels have a value less than 100. Maybe around 10% have a value above 200."
@@ -478,6 +515,7 @@
},
{
"cell_type": "markdown",
+ "id": "c8488b73",
"metadata": {},
"source": [
"**Q: repeat this exercise for another image, maybe `\"penguins.png\"` or `\"monalisa.png\"`.**"
@@ -485,6 +523,7 @@
},
{
"cell_type": "markdown",
+ "id": "75a08bb9",
"metadata": {},
"source": [
"# Binary images\n",
@@ -495,6 +534,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "703d0bf0",
"metadata": {},
"outputs": [],
"source": [
@@ -504,6 +544,7 @@
},
{
"cell_type": "markdown",
+ "id": "ddc94de2",
"metadata": {},
"source": [
"Now let's look at another grey scale image."
@@ -512,6 +553,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "2872e646",
"metadata": {},
"outputs": [],
"source": [
@@ -522,6 +564,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "893e8709",
"metadata": {},
"outputs": [],
"source": [
@@ -530,6 +573,7 @@
},
{
"cell_type": "markdown",
+ "id": "d0e2eaa6",
"metadata": {},
"source": [
"This time we see a much richer distribution of pixel values. A lot of pixels have a value less than 100 and these are the dark background of the sign. Clearly there are many shades of black. Similarly for the foreground, there are many shades of white.\n",
@@ -544,6 +588,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "4b9ee022",
"metadata": {},
"outputs": [],
"source": [
@@ -554,6 +599,7 @@
},
{
"cell_type": "markdown",
+ "id": "053aab60",
"metadata": {},
"source": [
"We now have only two types of pixels, black (value of 0) or white (value of 1), but they don't cleanly map to what we perceive as the black and white parts of the image.\n",
@@ -565,6 +611,7 @@
},
{
"cell_type": "markdown",
+ "id": "27eaccbf",
"metadata": {},
"source": [
"An easier way to do this is to add a control slider to interactively set the threshold.\n",
@@ -575,6 +622,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "078274c5",
"metadata": {},
"outputs": [],
"source": [
@@ -587,6 +635,7 @@
},
{
"cell_type": "markdown",
+ "id": "bc95d164",
"metadata": {},
"source": [
"**Q: adjust the threshold using the widget below, and explore the effect on the image. Try to find a threshold that yields a binary image where black corresponds to the background of the sign and white corresponds to the foreground text.**"
@@ -594,6 +643,7 @@
},
{
"cell_type": "markdown",
+ "id": "444fe16b",
"metadata": {},
"source": [
"# Challenges with thresholding\n",
@@ -604,6 +654,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "c2dade10",
"metadata": {},
"outputs": [],
"source": [
@@ -614,6 +665,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "b2480683",
"metadata": {},
"outputs": [],
"source": [
@@ -624,6 +676,7 @@
},
{
"cell_type": "markdown",
+ "id": "13e1168d",
"metadata": {},
"source": [
"This histogram is more bimodal, that is there are two peaks. \n",
@@ -635,6 +688,7 @@
},
{
"cell_type": "markdown",
+ "id": "c82336cc",
"metadata": {},
"source": [
"**Q: Using the widget try to find a good threshold that separates the lettering of the sign from the background**"
@@ -643,6 +697,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "7bea8d41",
"metadata": {},
"outputs": [],
"source": [
@@ -656,6 +711,7 @@
},
{
"cell_type": "markdown",
+ "id": "9b88d46a",
"metadata": {},
"source": [
"You will find that it is impossible to find a single threshold that separate all letters from the background. This is an example of the limitations of thresholding:\n",
@@ -673,52 +729,14 @@
],
"metadata": {
"kernelspec": {
- "display_name": "dev",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.10.16"
- },
- "varInspector": {
- "cols": {
- "lenName": 16,
- "lenType": 16,
- "lenVar": 40
- },
- "kernels_config": {
- "python": {
- "delete_cmd_postfix": "",
- "delete_cmd_prefix": "del ",
- "library": "var_list.py",
- "varRefreshCmd": "print(var_dic_list())"
- },
- "r": {
- "delete_cmd_postfix": ") ",
- "delete_cmd_prefix": "rm(",
- "library": "var_list.r",
- "varRefreshCmd": "cat(var_dic_list()) "
- }
- },
- "types_to_exclude": [
- "module",
- "function",
- "builtin_function_or_method",
- "instance",
- "_Feature"
- ],
- "window_display": false
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 4
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/homogeneous-coords.ipynb b/docs/notebooks/homogeneous-coords.ipynb
index 2224ab8a..b1a9baf6 100644
--- a/docs/notebooks/homogeneous-coords.ipynb
+++ b/docs/notebooks/homogeneous-coords.ipynb
@@ -2,12 +2,13 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "81f771d5",
"metadata": {},
"source": [
"\n",
" \n",
" Homogeneous coordinates | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -18,106 +19,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
- "\n",
- "\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
- "\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
- "\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
- "\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
+ "\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
+ "\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
+ "\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -126,6 +124,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "849d7961",
"metadata": {},
"outputs": [],
"source": [
@@ -141,6 +140,7 @@
},
{
"cell_type": "markdown",
+ "id": "52ee85b6",
"metadata": {},
"source": [
"***\n",
@@ -158,6 +158,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "8f4651a5",
"metadata": {},
"outputs": [],
"source": [
@@ -167,6 +168,7 @@
},
{
"cell_type": "markdown",
+ "id": "3840f3aa",
"metadata": {},
"source": [
"Note that `colvec` is a convenience function defined in `common.py`.\n",
@@ -177,6 +179,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "4fc5784e",
"metadata": {},
"outputs": [],
"source": [
@@ -186,6 +189,7 @@
},
{
"cell_type": "markdown",
+ "id": "91ddde50",
"metadata": {},
"source": [
"but we have defined another convenience function `e2h`"
@@ -194,6 +198,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "66ec0eb3",
"metadata": {},
"outputs": [],
"source": [
@@ -202,6 +207,7 @@
},
{
"cell_type": "markdown",
+ "id": "2e9d6f64",
"metadata": {},
"source": [
"which does the same thing.\n",
@@ -211,6 +217,7 @@
},
{
"cell_type": "markdown",
+ "id": "e17f107b",
"metadata": {},
"source": [
"### Converting homogeneous coordinates to Euclidean coordinates\n",
@@ -225,12 +232,14 @@
},
{
"cell_type": "markdown",
+ "id": "fb93a641",
"metadata": {},
"source": []
},
{
"cell_type": "code",
"execution_count": null,
+ "id": "fa51c821",
"metadata": {},
"outputs": [],
"source": [
@@ -241,6 +250,7 @@
},
{
"cell_type": "markdown",
+ "id": "2e91b3c5",
"metadata": {},
"source": [
"Once again, there is a convenience function for this called `h2e`"
@@ -249,6 +259,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "26aa47eb",
"metadata": {},
"outputs": [],
"source": [
@@ -258,6 +269,7 @@
},
{
"cell_type": "markdown",
+ "id": "8ed1c69d",
"metadata": {},
"source": [
"A key property of homogeneous coordinates is that the overall scale does not matter, that is $\\tilde{p}$ is equivalent to $\\lambda \\tilde{p}$ so long as $\\lambda \\ne 0$. Again this is easy to confirm"
@@ -266,6 +278,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "252cd8fc",
"metadata": {},
"outputs": [],
"source": [
@@ -274,6 +287,7 @@
},
{
"cell_type": "markdown",
+ "id": "41cd2205",
"metadata": {},
"source": [
"gives the same answer as above.\n",
@@ -283,6 +297,7 @@
},
{
"cell_type": "markdown",
+ "id": "b6284f75",
"metadata": {},
"source": [
"## Visualising homgeneous coordinates\n",
@@ -293,6 +308,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "b7b5db77",
"metadata": {},
"outputs": [],
"source": [
@@ -335,7 +351,7 @@
"@widgets.interact\n",
"def animate( x = widgets.FloatSlider(value=2, description='x:', min=-4, max=4),\n",
" y = widgets.FloatSlider(value=3, description='y:', min=-4, max=4),\n",
- " lam = widgets.FloatSlider(value=1, description='\ud835\udf06', min=0.2, max=5)):\n",
+ " lam = widgets.FloatSlider(value=1, description='𝜆', min=0.2, max=5)):\n",
" \n",
" # Update the quiver (arrow)\n",
" global quiver, scatter\n",
@@ -353,11 +369,13 @@
},
{
"cell_type": "markdown",
+ "id": "8b05e5c1",
"metadata": {},
"source": []
},
{
"cell_type": "markdown",
+ "id": "2e3002a8",
"metadata": {},
"source": [
"## Point equation of a line\n",
@@ -384,6 +402,7 @@
},
{
"cell_type": "markdown",
+ "id": "c0f9b74f",
"metadata": {},
"source": [
"## Join of two points in the Euclidean plane\n",
@@ -394,6 +413,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "7fe050fc",
"metadata": {},
"outputs": [],
"source": [
@@ -403,6 +423,7 @@
},
{
"cell_type": "markdown",
+ "id": "0bab3e2a",
"metadata": {},
"source": [
"which we can convert to homogeneous form"
@@ -411,6 +432,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1b1a14e6",
"metadata": {},
"outputs": [],
"source": [
@@ -422,6 +444,7 @@
},
{
"cell_type": "markdown",
+ "id": "a961f24a",
"metadata": {},
"source": [
"A line joining these two points is given by the cross product"
@@ -430,6 +453,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "cd17de54",
"metadata": {},
"outputs": [],
"source": [
@@ -439,6 +463,7 @@
},
{
"cell_type": "markdown",
+ "id": "48749e40",
"metadata": {},
"source": [
"Note that the numpy cross method only accepts row vectors.
\n",
@@ -449,6 +474,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "cdf4a8a5",
"metadata": {},
"outputs": [],
"source": [
@@ -462,6 +488,7 @@
},
{
"cell_type": "markdown",
+ "id": "77973187",
"metadata": {},
"source": [
"## Intersection of two lines in the Euclidean plane\n",
@@ -477,6 +504,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "69900036",
"metadata": {},
"outputs": [],
"source": [
@@ -486,6 +514,7 @@
},
{
"cell_type": "markdown",
+ "id": "3a938b72",
"metadata": {},
"source": [
"The intersection point of the two lines is the homogeneous point given by the cross product"
@@ -494,6 +523,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "fe00248e",
"metadata": {},
"outputs": [],
"source": [
@@ -504,6 +534,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "345e0369",
"metadata": {},
"outputs": [],
"source": [
@@ -522,12 +553,14 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "eb965854",
"metadata": {},
"outputs": [],
"source": []
},
{
"cell_type": "markdown",
+ "id": "cbb2f945",
"metadata": {},
"source": [
"## Parallel lines\n",
@@ -542,6 +575,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "4279e3e7",
"metadata": {},
"outputs": [],
"source": [
@@ -553,6 +587,7 @@
},
{
"cell_type": "markdown",
+ "id": "5640282f",
"metadata": {},
"source": [
"which we see has its third element equal to zero. This is an ideal point or a point at infinity. Bottom line, two parallel lines intersect at infinity. "
@@ -560,6 +595,7 @@
},
{
"cell_type": "markdown",
+ "id": "1aca4035",
"metadata": {},
"source": [
"# Key points\n",
@@ -575,52 +611,14 @@
],
"metadata": {
"kernelspec": {
- "display_name": "dev",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.10.16"
- },
- "varInspector": {
- "cols": {
- "lenName": 16,
- "lenType": 16,
- "lenVar": 40
- },
- "kernels_config": {
- "python": {
- "delete_cmd_postfix": "",
- "delete_cmd_prefix": "del ",
- "library": "var_list.py",
- "varRefreshCmd": "print(var_dic_list())"
- },
- "r": {
- "delete_cmd_postfix": ") ",
- "delete_cmd_prefix": "rm(",
- "library": "var_list.r",
- "varRefreshCmd": "cat(var_dic_list()) "
- }
- },
- "types_to_exclude": [
- "module",
- "function",
- "builtin_function_or_method",
- "instance",
- "_Feature"
- ],
- "window_display": false
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 4
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/homography.ipynb b/docs/notebooks/homography.ipynb
index 6a839b69..90db1862 100644
--- a/docs/notebooks/homography.ipynb
+++ b/docs/notebooks/homography.ipynb
@@ -2,6 +2,7 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "b4764522",
"metadata": {
"id": "GOBPjUzoqL5j"
},
@@ -9,7 +10,7 @@
"\n",
" \n",
" Planar homography | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -20,6 +21,7 @@
},
{
"cell_type": "markdown",
+ "id": "61e45de3",
"metadata": {
"id": "l-p9YGCUqRra"
},
@@ -31,106 +33,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
"\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
"\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
"\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
- "\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
- "\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -139,6 +138,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "e565d15a",
"metadata": {
"id": "NGGDoC29qR1a"
},
@@ -156,6 +156,7 @@
},
{
"cell_type": "markdown",
+ "id": "0e86b373",
"metadata": {
"id": "CNcehwNmqL5t"
},
@@ -168,6 +169,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "88e7623d",
"metadata": {
"id": "vAIz_xK9qL5u"
},
@@ -179,6 +181,7 @@
},
{
"cell_type": "markdown",
+ "id": "3ea9a16a",
"metadata": {},
"source": [
"And we can plot the camera in the 3D world"
@@ -187,6 +190,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "b8a6e8ad",
"metadata": {},
"outputs": [],
"source": [
@@ -198,6 +202,7 @@
},
{
"cell_type": "markdown",
+ "id": "5ad08bc0",
"metadata": {
"id": "ZNY-AQvCqL5u"
},
@@ -208,6 +213,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "cce6a120",
"metadata": {
"id": "THUZYQIsqL5v"
},
@@ -219,6 +225,7 @@
},
{
"cell_type": "markdown",
+ "id": "a2352ed8",
"metadata": {
"id": "pY0n-LzTqL5w"
},
@@ -229,6 +236,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "55d7ed9d",
"metadata": {},
"outputs": [],
"source": [
@@ -238,6 +246,7 @@
},
{
"cell_type": "markdown",
+ "id": "4f78fdb5",
"metadata": {},
"source": [
"Now we can project the 3D ground plane points onto the image plane"
@@ -246,6 +255,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "f86025a9",
"metadata": {
"id": "xYqu8FTkqL5w"
},
@@ -256,6 +266,7 @@
},
{
"cell_type": "markdown",
+ "id": "41565cad",
"metadata": {
"id": "Mqfb7FI9qL5w"
},
@@ -266,6 +277,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "a3f92dda",
"metadata": {
"id": "PvetB5hLqL5x"
},
@@ -277,6 +289,7 @@
},
{
"cell_type": "markdown",
+ "id": "16657b91",
"metadata": {
"id": "1TlYJip_qL5x"
},
@@ -287,6 +300,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "e15e403b",
"metadata": {
"id": "FvypDqy7qL5y"
},
@@ -297,6 +311,7 @@
},
{
"cell_type": "markdown",
+ "id": "ec4c5576",
"metadata": {
"id": "8MuxmN4lqL5y"
},
@@ -307,6 +322,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "2e629e27",
"metadata": {
"id": "hZQayaEwqL5z"
},
@@ -317,6 +333,7 @@
},
{
"cell_type": "markdown",
+ "id": "9d912870",
"metadata": {},
"source": [
"which first converts `P` to homogeneous form, performs the multiplication, then converts the resulting homogeneous coordinates to Euclidean."
@@ -324,6 +341,7 @@
},
{
"cell_type": "markdown",
+ "id": "6c4bfb05",
"metadata": {},
"source": [
"\n",
@@ -336,6 +354,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "49b3529f",
"metadata": {},
"outputs": [],
"source": [
@@ -345,6 +364,7 @@
},
{
"cell_type": "markdown",
+ "id": "330972df",
"metadata": {},
"source": [
"and on the ground plane these are the points"
@@ -353,6 +373,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "561d4ecc",
"metadata": {},
"outputs": [],
"source": [
@@ -362,6 +383,7 @@
},
{
"cell_type": "markdown",
+ "id": "e7bed13e",
"metadata": {},
"source": [
"Now we can overlay the corners of the camera's field of view onto the \"world view\" of the imaging setup that we showed earlier"
@@ -370,6 +392,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "d6e97f22",
"metadata": {},
"outputs": [],
"source": [
@@ -380,6 +403,7 @@
},
{
"cell_type": "markdown",
+ "id": "9f6ef915",
"metadata": {},
"source": [
"Scroll back up to the previous figure to see the blue dashed line representing the field of view."
@@ -387,57 +411,15 @@
}
],
"metadata": {
- "colab": {
- "name": "camera.ipynb",
- "provenance": []
- },
"kernelspec": {
- "display_name": "RVSS",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.10.19"
- },
- "varInspector": {
- "cols": {
- "lenName": 16,
- "lenType": 16,
- "lenVar": 40
- },
- "kernels_config": {
- "python": {
- "delete_cmd_postfix": "",
- "delete_cmd_prefix": "del ",
- "library": "var_list.py",
- "varRefreshCmd": "print(var_dic_list())"
- },
- "r": {
- "delete_cmd_postfix": ") ",
- "delete_cmd_prefix": "rm(",
- "library": "var_list.r",
- "varRefreshCmd": "cat(var_dic_list()) "
- }
- },
- "types_to_exclude": [
- "module",
- "function",
- "builtin_function_or_method",
- "instance",
- "_Feature"
- ],
- "window_display": false
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 0
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/image-convolution.ipynb b/docs/notebooks/image-convolution.ipynb
index c7d65e25..a275ce5e 100644
--- a/docs/notebooks/image-convolution.ipynb
+++ b/docs/notebooks/image-convolution.ipynb
@@ -2,12 +2,13 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "cf56fd88",
"metadata": {},
"source": [
"\n",
" \n",
" Spatial Operators | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -18,6 +19,7 @@
},
{
"cell_type": "markdown",
+ "id": "c48a65b8",
"metadata": {},
"source": [
"## Configuring the Jupyter environment\n",
@@ -27,106 +29,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
- "\n",
- "\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
"\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
"\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
"\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -135,6 +134,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "18b056b4",
"metadata": {},
"outputs": [],
"source": [
@@ -154,6 +154,7 @@
},
{
"cell_type": "markdown",
+ "id": "35fe8b7a",
"metadata": {},
"source": [
"Now let's load a real greyscale image from a PNG file. This particular image file is distributed with the Toolbox, but you can pass in the path to any image file you might have. _If the Toolbox can't find the specified image it defaults to looking in the folder of images distributed with the Toolbox._"
@@ -162,6 +163,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "a8d2039f",
"metadata": {},
"outputs": [],
"source": [
@@ -171,6 +173,7 @@
},
{
"cell_type": "markdown",
+ "id": "a827416a",
"metadata": {},
"source": [
"The image of the Mona Lisa looks rather grainy, the paint is cracked, but then she is over 500 years old...\n",
@@ -183,6 +186,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "4a3e66f5",
"metadata": {},
"outputs": [],
"source": [
@@ -192,6 +196,7 @@
},
{
"cell_type": "markdown",
+ "id": "7d4958e1",
"metadata": {},
"source": [
"where the sum of all values is equal to one. For a given input pixel, say (20,30), the $5 \\times 5$ window is"
@@ -200,6 +205,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ce60efac",
"metadata": {},
"outputs": [],
"source": [
@@ -209,6 +215,7 @@
},
{
"cell_type": "markdown",
+ "id": "2b02fa3d",
"metadata": {},
"source": [
"Note that the range 20-2:20+3 includes 20-2, 20-1, 20-0, 20+1, 20+2. In Python the end value of a range is not included in the set.
"
@@ -217,6 +224,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "cceb732b",
"metadata": {},
"outputs": [],
"source": [
@@ -227,6 +235,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "a5871b58",
"metadata": {},
"outputs": [],
"source": [
@@ -235,6 +244,7 @@
},
{
"cell_type": "markdown",
+ "id": "0e627e2b",
"metadata": {},
"source": [
"and this is the value of pixel (20,30) in the output image. \n",
@@ -245,6 +255,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "f808d985",
"metadata": {},
"outputs": [],
"source": [
@@ -254,6 +265,7 @@
},
{
"cell_type": "markdown",
+ "id": "1e9d44d6",
"metadata": {},
"source": [
"**Q: Vary the dimensions of the kernel to see what effect it has?**"
@@ -261,6 +273,7 @@
},
{
"cell_type": "markdown",
+ "id": "b74fa854",
"metadata": {},
"source": [
"The square window can introduce artifact in the image, horizontal lines induced by contrast steps. When `n` is large the monalisa develops a moustache!\n",
@@ -270,6 +283,7 @@
},
{
"cell_type": "markdown",
+ "id": "601f2a75",
"metadata": {},
"source": [
"## Gaussian blur"
@@ -277,6 +291,7 @@
},
{
"cell_type": "markdown",
+ "id": "0e1251c1",
"metadata": {},
"source": [
"For image smoothing it is preferable to use a kernel that is isotropic and symmetric such as a 2D Gaussian\n",
@@ -286,6 +301,7 @@
},
{
"cell_type": "markdown",
+ "id": "27f93018",
"metadata": {},
"source": [
" We will create a 2D Gaussian with $\\sigma=10$"
@@ -294,6 +310,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "a98aec0c",
"metadata": {},
"outputs": [],
"source": [
@@ -303,6 +320,7 @@
},
{
"cell_type": "markdown",
+ "id": "07fd5a28",
"metadata": {},
"source": [
"We can display the kernel as a 3-dimensional mesh."
@@ -311,6 +329,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "a4b8356e",
"metadata": {},
"outputs": [],
"source": [
@@ -319,6 +338,7 @@
},
{
"cell_type": "markdown",
+ "id": "94d859a4",
"metadata": {},
"source": [
"Now we can convolve the image with this kernel"
@@ -327,6 +347,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "afd4d511",
"metadata": {},
"outputs": [],
"source": [
@@ -335,6 +356,7 @@
},
{
"cell_type": "markdown",
+ "id": "3af75171",
"metadata": {},
"source": [
"We can do this more simply using the `smooth` method which accepts $\\sigma$ and the half-kernel width."
@@ -343,6 +365,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "392687d2",
"metadata": {},
"outputs": [],
"source": [
@@ -351,6 +374,7 @@
},
{
"cell_type": "markdown",
+ "id": "80aae49e",
"metadata": {},
"source": [
"**Q: Modify the code block above and look at the effect of changing $\\sigma$**"
@@ -358,6 +382,7 @@
},
{
"cell_type": "markdown",
+ "id": "37bcf017",
"metadata": {},
"source": [
"## Finding edges\n",
@@ -367,6 +392,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "4036d40e",
"metadata": {},
"outputs": [],
"source": [
@@ -377,6 +403,7 @@
},
{
"cell_type": "markdown",
+ "id": "cc39eefe",
"metadata": {},
"source": [
"You may often see this filter kernel written with the first and third columns swapped. This is appropriate if you perform correlation, not convolution. These are two similar operations but differ in the kernel being reflected about its centre. Many kernels are symmetric which means that convolution and correlation are the same.
"
@@ -385,6 +412,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "5ba2bd41",
"metadata": {},
"outputs": [],
"source": [
@@ -395,6 +423,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "c876eb66",
"metadata": {},
"outputs": [],
"source": [
@@ -404,6 +433,7 @@
},
{
"cell_type": "markdown",
+ "id": "915a4006",
"metadata": {},
"source": [
"The image is displayed with a color map that shows negative numbers as red and positive numbers as blue. Zoom in on the outline of the \"P\" (use the second button from the right in the bottom toolbar) and you can see that the intensity goes up (blue) on the left side of the \"P\", from the grey background to the white paint. It goes down (red) on right of the stem, from the white paint to the gray background.\n",
@@ -416,6 +446,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "5659b338",
"metadata": {},
"outputs": [],
"source": [
@@ -426,23 +457,14 @@
],
"metadata": {
"kernelspec": {
- "display_name": "dev",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.12.8"
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/image-features.ipynb b/docs/notebooks/image-features.ipynb
index 4a01bacc..c1d5a0c3 100644
--- a/docs/notebooks/image-features.ipynb
+++ b/docs/notebooks/image-features.ipynb
@@ -2,6 +2,7 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "db0193d3",
"metadata": {
"id": "E_0aEaFYzu5L"
},
@@ -9,7 +10,7 @@
"\n",
" \n",
" Image Features | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -20,6 +21,7 @@
},
{
"cell_type": "markdown",
+ "id": "8366c05d",
"metadata": {
"id": "fJjzn-jIzu5O"
},
@@ -31,106 +33,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
- "\n",
- "\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
- "\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
- "\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
- "\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
+ "\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
+ "\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
+ "\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -139,6 +138,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ce576248",
"metadata": {
"id": "puZNEjc1zu5O"
},
@@ -157,6 +157,7 @@
},
{
"cell_type": "markdown",
+ "id": "7d9abb2d",
"metadata": {
"id": "86KrKDQYzu5a"
},
@@ -167,6 +168,7 @@
},
{
"cell_type": "markdown",
+ "id": "ccc41907",
"metadata": {
"id": "VSN7ZQULzu5a"
},
@@ -177,6 +179,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "cc28a3f5",
"metadata": {
"id": "DoHQMxJNzu5b"
},
@@ -188,6 +191,7 @@
},
{
"cell_type": "markdown",
+ "id": "37ee124a",
"metadata": {
"id": "YeWq8RK0zu5b"
},
@@ -205,6 +209,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "211acc43",
"metadata": {
"id": "KN3aO2WBzu5b"
},
@@ -234,6 +239,7 @@
},
{
"cell_type": "markdown",
+ "id": "31159dc1",
"metadata": {
"id": "7qS6voZgzu5c"
},
@@ -263,6 +269,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "213e649b",
"metadata": {
"id": "YBUHD26dzu5c"
},
@@ -274,6 +281,7 @@
},
{
"cell_type": "markdown",
+ "id": "c98a537c",
"metadata": {
"id": "vLiSZ45Uzu5c"
},
@@ -286,6 +294,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "34aebffa",
"metadata": {
"id": "URXGVC_vzu5d"
},
@@ -301,6 +310,7 @@
},
{
"cell_type": "markdown",
+ "id": "b51c140f",
"metadata": {
"id": "WQ8eT2HMzu5d"
},
@@ -313,6 +323,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "0209ffa7",
"metadata": {
"id": "6aGCCwBPzu5d"
},
@@ -335,6 +346,7 @@
},
{
"cell_type": "markdown",
+ "id": "ae66e61b",
"metadata": {
"id": "3BBbrRIvzu5e"
},
@@ -350,6 +362,7 @@
},
{
"cell_type": "markdown",
+ "id": "91d87b9f",
"metadata": {
"id": "wKETKTF_zu5e"
},
@@ -360,6 +373,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "6de74370",
"metadata": {
"id": "2RBNZgm0zu5e"
},
@@ -371,6 +385,7 @@
},
{
"cell_type": "markdown",
+ "id": "945ad95b",
"metadata": {
"id": "MVCIPAtmzu5e"
},
@@ -381,6 +396,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "26a3a478",
"metadata": {
"id": "xrTcjTrszu5e"
},
@@ -391,6 +407,7 @@
},
{
"cell_type": "markdown",
+ "id": "05541a88",
"metadata": {
"id": "dp6HbEZBzu5f"
},
@@ -401,6 +418,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "7ca7e05a",
"metadata": {
"id": "Aw6ha2Oszu5f"
},
@@ -411,6 +429,7 @@
},
{
"cell_type": "markdown",
+ "id": "6829d996",
"metadata": {
"id": "HuWcaoCpzu5f"
},
@@ -423,6 +442,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "f1a00350",
"metadata": {
"id": "6Qgnd_spzu5f"
},
@@ -433,6 +453,7 @@
},
{
"cell_type": "markdown",
+ "id": "59649bdd",
"metadata": {
"id": "kf1hXxNezu5f"
},
@@ -443,6 +464,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1bda4b2c",
"metadata": {
"id": "AhMxtoA5zu5f"
},
@@ -453,6 +475,7 @@
},
{
"cell_type": "markdown",
+ "id": "6a60a423",
"metadata": {
"id": "DFLjAzUCzu5f"
},
@@ -463,6 +486,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "3e76a891",
"metadata": {
"id": "uu_rwnXxzu5g"
},
@@ -473,6 +497,7 @@
},
{
"cell_type": "markdown",
+ "id": "c5bc3d6e",
"metadata": {
"id": "hZnHEzBfzu5g"
},
@@ -483,6 +508,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "be45c4b5",
"metadata": {
"id": "FrBa7fgozu5g"
},
@@ -493,6 +519,7 @@
},
{
"cell_type": "markdown",
+ "id": "8244ab72",
"metadata": {
"id": "6MyGyz9azu5g"
},
@@ -505,6 +532,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "df8af6dc",
"metadata": {
"id": "Q2fGdtV2zu5g"
},
@@ -515,6 +543,7 @@
},
{
"cell_type": "markdown",
+ "id": "4133c1ff",
"metadata": {
"id": "CWmYXsAszu5g"
},
@@ -525,6 +554,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "5f93f067",
"metadata": {
"id": "_m8xzaqYzu5g"
},
@@ -535,6 +565,7 @@
},
{
"cell_type": "markdown",
+ "id": "b0c82e52",
"metadata": {
"id": "XsiOyCV-zu5g"
},
@@ -545,6 +576,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "2ba63774",
"metadata": {
"id": "RNTWOTL6zu5g"
},
@@ -555,6 +587,7 @@
},
{
"cell_type": "markdown",
+ "id": "bd4dc126",
"metadata": {
"id": "nSQMy7mlzu5h"
},
@@ -565,6 +598,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ed482842",
"metadata": {
"id": "xQR_AlsLzu5h"
},
@@ -575,6 +609,7 @@
},
{
"cell_type": "markdown",
+ "id": "14769638",
"metadata": {
"id": "z2yFAlKCzu5h"
},
@@ -585,6 +620,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "d79e80a7",
"metadata": {
"id": "A151FQJ0zu5h"
},
@@ -596,6 +632,7 @@
},
{
"cell_type": "markdown",
+ "id": "09151289",
"metadata": {
"id": "T56heJfFzu5h"
},
@@ -610,6 +647,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "3127d58b",
"metadata": {
"id": "TfSWo6QUzu5h"
},
@@ -620,6 +658,7 @@
},
{
"cell_type": "markdown",
+ "id": "8ce52314",
"metadata": {
"id": "d6egtJLuzu5i"
},
@@ -632,6 +671,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "8beaac19",
"metadata": {
"id": "_Q9LZvqgzu5i"
},
@@ -643,6 +683,7 @@
},
{
"cell_type": "markdown",
+ "id": "fe2eb0b4",
"metadata": {
"id": "Cx-IVNWyzu5i"
},
@@ -652,6 +693,7 @@
},
{
"cell_type": "markdown",
+ "id": "99323cc8",
"metadata": {
"id": "QWtuQDZwzu5i"
},
@@ -664,6 +706,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "31a74c23",
"metadata": {
"id": "v-cdFeY4zu5i"
},
@@ -676,6 +719,7 @@
},
{
"cell_type": "markdown",
+ "id": "8b3df306",
"metadata": {
"id": "fEo8EqT3Qv-x"
},
@@ -686,6 +730,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "103a970f",
"metadata": {
"id": "md1S7iLHQweC"
},
@@ -698,6 +743,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "4a216d71",
"metadata": {},
"outputs": [],
"source": [
@@ -706,6 +752,7 @@
},
{
"cell_type": "markdown",
+ "id": "e607bd9e",
"metadata": {
"id": "xT7AIsA7zu5i"
},
@@ -716,6 +763,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "63e05e08",
"metadata": {
"id": "tFT_GbQKzu5j"
},
@@ -727,6 +775,7 @@
},
{
"cell_type": "markdown",
+ "id": "f330eb95",
"metadata": {
"id": "sZQtJ7mPzu5j"
},
@@ -737,6 +786,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "bbc096d4",
"metadata": {
"id": "jM5XWcKzzu5j"
},
@@ -747,6 +797,7 @@
},
{
"cell_type": "markdown",
+ "id": "5868cedf",
"metadata": {
"id": "uDIAtRqSzu5j"
},
@@ -758,78 +809,15 @@
}
],
"metadata": {
- "accelerator": "GPU",
- "colab": {
- "include_colab_link": true,
- "name": "image-features.ipynb",
- "provenance": [],
- "toc_visible": true
- },
"kernelspec": {
- "display_name": "dev",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.12.8"
- },
- "toc": {
- "base_numbering": 1,
- "nav_menu": {},
- "number_sections": true,
- "sideBar": true,
- "skip_h1_title": false,
- "title_cell": "Table of Contents",
- "title_sidebar": "Contents",
- "toc_cell": false,
- "toc_position": {
- "height": "calc(100% - 180px)",
- "left": "10px",
- "top": "150px",
- "width": "181.59375px"
- },
- "toc_section_display": true,
- "toc_window_display": true
- },
- "varInspector": {
- "cols": {
- "lenName": 16,
- "lenType": 16,
- "lenVar": 40
- },
- "kernels_config": {
- "python": {
- "delete_cmd_postfix": "",
- "delete_cmd_prefix": "del ",
- "library": "var_list.py",
- "varRefreshCmd": "print(var_dic_list())"
- },
- "r": {
- "delete_cmd_postfix": ") ",
- "delete_cmd_prefix": "rm(",
- "library": "var_list.r",
- "varRefreshCmd": "cat(var_dic_list()) "
- }
- },
- "types_to_exclude": [
- "module",
- "function",
- "builtin_function_or_method",
- "instance",
- "_Feature"
- ],
- "window_display": false
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 0
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/image-motion.ipynb b/docs/notebooks/image-motion.ipynb
index 690394f2..64fd3b7e 100644
--- a/docs/notebooks/image-motion.ipynb
+++ b/docs/notebooks/image-motion.ipynb
@@ -2,6 +2,7 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "1f342fd7",
"metadata": {
"id": "8VwKU8E-k5E4"
},
@@ -9,7 +10,7 @@
"\n",
" \n",
" Camera and image motion | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -20,6 +21,7 @@
},
{
"cell_type": "markdown",
+ "id": "eea4ac38",
"metadata": {},
"source": [
"## Configuring the Jupyter environment\n",
@@ -29,106 +31,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
- "\n",
- "\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
- "\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
- "\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
- "\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
+ "\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
+ "\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
+ "\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -137,6 +136,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "3167ed9e",
"metadata": {
"id": "aPe_Bq05lHSV"
},
@@ -154,6 +154,7 @@
},
{
"cell_type": "markdown",
+ "id": "9d882bf2",
"metadata": {
"id": "zd7Kqzv-k5E6"
},
@@ -166,6 +167,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "4419069e",
"metadata": {
"id": "BlNstH2jk5E7"
},
@@ -177,6 +179,7 @@
},
{
"cell_type": "markdown",
+ "id": "2591038a",
"metadata": {
"id": "roUWApWQk5E7"
},
@@ -187,6 +190,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ea96ad5c",
"metadata": {
"id": "4XUUM2r8k5E7"
},
@@ -197,6 +201,7 @@
},
{
"cell_type": "markdown",
+ "id": "9f5c11e0",
"metadata": {
"id": "YWNEHg-jk5E8"
},
@@ -207,6 +212,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ce9ecde1",
"metadata": {
"id": "U_u4XYA9k5E8"
},
@@ -218,6 +224,7 @@
},
{
"cell_type": "markdown",
+ "id": "9b35e3dd",
"metadata": {
"id": "pQguQ0B7k5E8"
},
@@ -228,6 +235,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "358fd554",
"metadata": {
"id": "Aq2ganDok5E9"
},
@@ -240,6 +248,7 @@
},
{
"cell_type": "markdown",
+ "id": "4d5cfe90",
"metadata": {
"id": "8VQwAuCXk5E9"
},
@@ -250,6 +259,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "7af7936b",
"metadata": {
"id": "yCeNimA8k5E9"
},
@@ -260,11 +270,12 @@
},
{
"cell_type": "markdown",
+ "id": "62cd6f03",
"metadata": {
"id": "y8NBvdhAk5E9"
},
"source": [
- "which is an approximation to the partial derivative $\\partial p / \\partial x$. It shows that 1 m of camera motion would lead to \u2212160 pixel of feature motion in the u-direction. \n",
+ "which is an approximation to the partial derivative $\\partial p / \\partial x$. It shows that 1 m of camera motion would lead to −160 pixel of feature motion in the u-direction. \n",
"\n",
"We can repeat this for z-axis translation, ie. moving the camera forward\n"
]
@@ -272,6 +283,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "23e75d21",
"metadata": {
"id": "fi6Pnd7jk5E-"
},
@@ -282,6 +294,7 @@
},
{
"cell_type": "markdown",
+ "id": "9aef7482",
"metadata": {
"id": "kVPYkHgEk5E-"
},
@@ -294,6 +307,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "01660393",
"metadata": {
"id": "s-VqhlW3k5E_"
},
@@ -305,6 +319,7 @@
},
{
"cell_type": "markdown",
+ "id": "66ae8d52",
"metadata": {
"id": "lPUMIHhck5E_"
},
@@ -335,6 +350,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "cb8f3779",
"metadata": {
"id": "BAolhqz-k5FA"
},
@@ -346,6 +362,7 @@
},
{
"cell_type": "markdown",
+ "id": "7439fe67",
"metadata": {
"id": "7hJjXqTPk5FA"
},
@@ -358,6 +375,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "ec5ee5bc",
"metadata": {
"id": "ldKI8aT-k5FA"
},
@@ -368,6 +386,7 @@
},
{
"cell_type": "markdown",
+ "id": "8c579def",
"metadata": {
"id": "3_N7Jt7Ok5FB"
},
@@ -380,6 +399,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "21eaa626",
"metadata": {
"id": "ElFk0exUk5FB"
},
@@ -390,6 +410,7 @@
},
{
"cell_type": "markdown",
+ "id": "e024dc99",
"metadata": {
"id": "C9cnyycnk5FB"
},
@@ -400,6 +421,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "2687edec",
"metadata": {
"id": "tpMGqvfak5FB"
},
@@ -410,6 +432,7 @@
},
{
"cell_type": "markdown",
+ "id": "53cee8a1",
"metadata": {
"id": "sG1uHPQRk5FC"
},
@@ -424,6 +447,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "9a9c8bf6",
"metadata": {
"id": "veCIvlDWk5FC"
},
@@ -480,6 +504,7 @@
},
{
"cell_type": "markdown",
+ "id": "70f31fc0",
"metadata": {
"id": "cGZ4czlak5FD"
},
@@ -490,6 +515,7 @@
},
{
"cell_type": "markdown",
+ "id": "70b17205",
"metadata": {
"id": "k5Sk7ITdk5FD"
},
@@ -501,6 +527,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1a34512b",
"metadata": {
"id": "NzqTYA14k5FE"
},
@@ -514,6 +541,7 @@
},
{
"cell_type": "markdown",
+ "id": "d103965d",
"metadata": {
"id": "S0vqvf-zk5FE"
},
@@ -524,6 +552,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "150c7069",
"metadata": {
"id": "8-UzgBEyk5FE"
},
@@ -535,6 +564,7 @@
},
{
"cell_type": "markdown",
+ "id": "f3729d3e",
"metadata": {
"id": "TtsHJ6l1k5FE"
},
@@ -545,6 +575,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "103ad181",
"metadata": {
"id": "rwWKx48ek5FF"
},
@@ -555,6 +586,7 @@
},
{
"cell_type": "markdown",
+ "id": "e9057fb7",
"metadata": {
"id": "XsxUVkT2k5FF"
},
@@ -565,6 +597,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "7d53b7ad",
"metadata": {
"id": "lYXAhcyFk5FF"
},
@@ -575,6 +608,7 @@
},
{
"cell_type": "markdown",
+ "id": "3d1a6408",
"metadata": {
"id": "pZqWs9ODk5FF"
},
@@ -584,6 +618,7 @@
},
{
"cell_type": "markdown",
+ "id": "90644c79",
"metadata": {
"id": "6KBlWnPAk5FG"
},
@@ -594,6 +629,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "54175208",
"metadata": {
"id": "wu_pnsbCk5FG"
},
@@ -608,6 +644,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "378409b2",
"metadata": {
"id": "5bJyEPFOk5FG"
},
@@ -625,70 +662,15 @@
}
],
"metadata": {
- "colab": {
- "name": "ImageMotion.ipynb",
- "provenance": []
- },
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.10.12"
- },
- "toc": {
- "base_numbering": 1,
- "nav_menu": {},
- "number_sections": true,
- "sideBar": true,
- "skip_h1_title": false,
- "title_cell": "Table of Contents",
- "title_sidebar": "Contents",
- "toc_cell": false,
- "toc_position": {},
- "toc_section_display": true,
- "toc_window_display": true
- },
- "varInspector": {
- "cols": {
- "lenName": 16,
- "lenType": 16,
- "lenVar": 40
- },
- "kernels_config": {
- "python": {
- "delete_cmd_postfix": "",
- "delete_cmd_prefix": "del ",
- "library": "var_list.py",
- "varRefreshCmd": "print(var_dic_list())"
- },
- "r": {
- "delete_cmd_postfix": ") ",
- "delete_cmd_prefix": "rm(",
- "library": "var_list.r",
- "varRefreshCmd": "cat(var_dic_list()) "
- }
- },
- "types_to_exclude": [
- "module",
- "function",
- "builtin_function_or_method",
- "instance",
- "_Feature"
- ],
- "window_display": false
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 0
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/image-processing.ipynb b/docs/notebooks/image-processing.ipynb
index b81d6feb..1d2243b5 100644
--- a/docs/notebooks/image-processing.ipynb
+++ b/docs/notebooks/image-processing.ipynb
@@ -2,12 +2,13 @@
"cells": [
{
"cell_type": "markdown",
+ "id": "dd34516c",
"metadata": {},
"source": [
"\n",
" \n",
" Image Processing | \n",
- "  | \n",
+ "  | \n",
"
\n",
"
\n",
"\n",
@@ -18,6 +19,7 @@
},
{
"cell_type": "markdown",
+ "id": "9d1d5448",
"metadata": {},
"source": [
"## Configuring the Jupyter environment\n",
@@ -27,106 +29,103 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
- "\n",
- "\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
"\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
"\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
"\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -135,6 +134,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "8364cdfb",
"metadata": {},
"outputs": [],
"source": [
@@ -153,6 +153,7 @@
},
{
"cell_type": "markdown",
+ "id": "78772797",
"metadata": {},
"source": [
"# Monadic image operations\n",
@@ -163,6 +164,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "c159f27a",
"metadata": {},
"outputs": [],
"source": [
@@ -172,6 +174,7 @@
},
{
"cell_type": "markdown",
+ "id": "0653b5b2",
"metadata": {},
"source": [
"First, we display some simple statistics on the minimum and maximum pixel values"
@@ -180,6 +183,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "f486c804",
"metadata": {},
"outputs": [],
"source": [
@@ -188,6 +192,7 @@
},
{
"cell_type": "markdown",
+ "id": "5469de5a",
"metadata": {},
"source": [
"and we see that the average pixel value is well below the mid value of 128.\n",
@@ -198,6 +203,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "096d556b",
"metadata": {},
"outputs": [],
"source": [
@@ -207,6 +213,7 @@
},
{
"cell_type": "markdown",
+ "id": "ceeb6e3b",
"metadata": {},
"source": [
"and plot it"
@@ -215,6 +222,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "c5567abc",
"metadata": {},
"outputs": [],
"source": [
@@ -224,6 +232,7 @@
},
{
"cell_type": "markdown",
+ "id": "411daa96",
"metadata": {},
"source": [
"We can attempt to brighten the image by multiplying all the pixel values by 1.5. We need to be careful that the values don't exceed the range of the `uint8` type."
@@ -232,6 +241,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "d21470dc",
"metadata": {},
"outputs": [],
"source": [
@@ -240,6 +250,7 @@
},
{
"cell_type": "markdown",
+ "id": "7afcaef3",
"metadata": {},
"source": [
"A simple art effect is posterization where we quantise the pixel values"
@@ -248,6 +259,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "7673fbd7",
"metadata": {},
"outputs": [],
"source": [
@@ -256,6 +268,7 @@
},
{
"cell_type": "markdown",
+ "id": "61ce0e52",
"metadata": {},
"source": [
"And we can apply a threshold, testing whether or not each pixel value exceeds 100. The resulting image has pixel values which are either True or False"
@@ -264,6 +277,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "94eabc82",
"metadata": {},
"outputs": [],
"source": [
@@ -272,6 +286,7 @@
},
{
"cell_type": "markdown",
+ "id": "3ae09ef7",
"metadata": {},
"source": [
"# Green screening"
@@ -279,6 +294,7 @@
},
{
"cell_type": "markdown",
+ "id": "76c06465",
"metadata": {},
"source": [
"This is a very common technique in video production, and these days even with video conferencing tools. We load our foreground image, the one we'd like to superimpose on the background. In a video this would be the presenter."
@@ -287,6 +303,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "34cd9973",
"metadata": {},
"outputs": [],
"source": [
@@ -296,6 +313,7 @@
},
{
"cell_type": "markdown",
+ "id": "05f9cd5f",
"metadata": {},
"source": [
"Now we need to determine which pixels are green, the background to be discarded. We gamma decode the image and compute the chromacity of every pixel $r=R/(R+G+B), g=G/(R+G+B)$. The result is an image with two planes"
@@ -304,6 +322,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "41d742a3",
"metadata": {},
"outputs": [],
"source": [
@@ -313,6 +332,7 @@
},
{
"cell_type": "markdown",
+ "id": "033e6f88",
"metadata": {},
"source": [
"We will apply a threshold to $g$ but we need to understand the distribution before we can choose the threshold value. For that we'll compute and display a histogram."
@@ -321,6 +341,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "b8b409ab",
"metadata": {},
"outputs": [],
"source": [
@@ -334,6 +355,7 @@
},
{
"cell_type": "markdown",
+ "id": "54b6a0db",
"metadata": {},
"source": [
"The big strong green peak on the right is the green background, the other peak is the foreground object. A threshold of 0.45 nicely separates the two pixel populations."
@@ -342,6 +364,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "1bd53561",
"metadata": {},
"outputs": [],
"source": [
@@ -352,6 +375,7 @@
},
{
"cell_type": "markdown",
+ "id": "daa4d7bf",
"metadata": {},
"source": [
"The result is a logical image where True pixels indicate foreground pixels.\n",
@@ -362,6 +386,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "38394e23",
"metadata": {},
"outputs": [],
"source": [
@@ -371,6 +396,7 @@
},
{
"cell_type": "markdown",
+ "id": "23a2d7e8",
"metadata": {},
"source": [
"which we see is a color image where the R, G, and B planes are the image above.\n",
@@ -381,6 +407,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "e7f21288",
"metadata": {},
"outputs": [],
"source": [
@@ -389,6 +416,7 @@
},
{
"cell_type": "markdown",
+ "id": "2bcff437",
"metadata": {},
"source": [
"Happily, all the green pixels have now gone.\n",
@@ -399,6 +427,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "a76bf50a",
"metadata": {},
"outputs": [],
"source": [
@@ -407,6 +436,7 @@
},
{
"cell_type": "markdown",
+ "id": "141be03a",
"metadata": {},
"source": [
"and then apply the inverse mask to it. Note that in Python `True`=1 and `False`=0."
@@ -415,6 +445,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "5e58114a",
"metadata": {},
"outputs": [],
"source": [
@@ -423,6 +454,7 @@
},
{
"cell_type": "markdown",
+ "id": "c9341073",
"metadata": {},
"source": [
"Now, all that's left to do is to add the masked foreground image to the inverse masked background image"
@@ -431,6 +463,7 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "7d59ba8e",
"metadata": {},
"outputs": [],
"source": [
@@ -440,23 +473,14 @@
],
"metadata": {
"kernelspec": {
- "display_name": "dev",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.10.16"
+ "name": "python"
}
},
"nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 5
}
diff --git a/docs/notebooks/index.ipynb b/docs/notebooks/index.ipynb
index 03066a6b..374fa094 100644
--- a/docs/notebooks/index.ipynb
+++ b/docs/notebooks/index.ipynb
@@ -9,7 +9,7 @@
"\n",
"\n",
" \n",
- "  | \n",
+ "  | \n",
" Interactive Browser Tutorials & Demos | \n",
"
\n",
"
\n",
@@ -60,7 +60,7 @@
"\n",
"---\n",
"\n",
- "
\n",
+ "
\n",
"
\n",
" Created by Peter Corke | QUT Centre for Robotics\n",
"
"
@@ -69,21 +69,12 @@
],
"metadata": {
"kernelspec": {
- "display_name": "dev",
+ "display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.12.8"
+ "name": "python"
}
},
"nbformat": 4,
diff --git a/docs/notebooks/intro.ipynb b/docs/notebooks/intro.ipynb
index 57b479ec..6ca31fef 100644
--- a/docs/notebooks/intro.ipynb
+++ b/docs/notebooks/intro.ipynb
@@ -4,110 +4,107 @@
"cell_type": "markdown",
"id": "0f90fd53",
"metadata": {},
- "source": "\n \n Machine Vision Toolbox for Python \u2014 Interactive Demo | \n  | \n
\n
\n\nA quick, runnable introduction to the toolbox. Works locally, on Google Colab, or entirely in your browser via [JupyterLite](https://jupyterlite.readthedocs.io) and [Pyodide](https://pyodide.org) -- no installation required either way. The cell below installs the toolbox the first time it is run (and will take a few seconds on Colab or in the browser)."
+ "source": "\n \n Machine Vision Toolbox for Python — Interactive Demo | \n  | \n
\n
\n\nA quick, runnable introduction to the toolbox. Works locally, on Google Colab, or entirely in your browser via [JupyterLite](https://jupyterlite.readthedocs.io) and [Pyodide](https://pyodide.org) -- no installation required either way. The cell below installs the toolbox the first time it is run (and will take a few seconds on Colab or in the browser)."
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "mvtb-bootstrap-cell",
"metadata": {
"jupyter": {
"source_hidden": true
}
},
- "execution_count": null,
"outputs": [],
"source": [
- "# MVTB_BOOTSTRAP_CELL -- sets up the environment (Colab / JupyterLite / local install); click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by sync_bootstrap.py -- do not hand-edit.\n",
- "\n",
- "\"\"\"Environment bootstrap for machinevision-toolbox-python's Jupyter notebooks.\n",
- "\n",
- "Installs the toolbox (and reports how) across the three environments a notebook in\n",
- "this folder might run in: a local Jupyter/VS Code install, Google Colab, and\n",
- "JupyterLite (Pyodide/WASM, in-browser).\n",
- "\n",
- "This file is the single source of truth for that logic. Every notebook's own\n",
- "bootstrap cell is a generated copy of this file's content, produced by\n",
- "sync_bootstrap.py -- see docs/notebooks/README.md for the full explanation.\n",
- "\"\"\"\n",
+ "# MVTB_BOOTSTRAP_CELL: installs the package, which takes a short time, so wait for the line \"Running ...\" below. Generated by sync_bootstrap.py from _mvtb_nb_bootstrap.py, do not edit\n",
"\n",
"import subprocess\n",
"import sys\n",
- "from pathlib import Path\n",
- "\n",
- "\n",
- "async def ensure_installed() -> bool:\n",
- " \"\"\"Install machinevision-toolbox-python if needed, and report the environment.\n",
+ "PACKAGE = 'machinevision-toolbox-python'\n",
+ "IMPORT_NAME = 'machinevisiontoolbox'\n",
+ "GIT_URL: str | None = 'https://github.com/petercorke/machinevision-toolbox-python'\n",
+ "JL_PACKAGES = ['numpy', 'scipy', 'matplotlib', 'pillow', 'typing_extensions', 'opencv-python', 'ansitable', 'mvtb-data', 'tqdm', 'requests', 'ipywidgets', 'spatialmath-python', 'pgraph-python']\n",
+ "JL_NO_DEPS: list[str] = []\n",
+ "JL_PACKAGE_NO_DEPS = True\n",
+ "JL_EXTRAS: dict[str, list[str]] = {}\n",
+ "COLAB_PACKAGES: list[str] = []\n",
"\n",
- " :returns: True if running on Google Colab, False otherwise.\n",
- " \"\"\"\n",
- " if sys.platform == \"emscripten\":\n",
- " import micropip\n",
+ "def _version_of(package: str, module) -> str:\n",
+ " import importlib.metadata\n",
+ " try:\n",
+ " return importlib.metadata.version(package)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " return str(getattr(module, '__version__', 'unknown'))\n",
"\n",
- " await micropip.install(\n",
- " [\n",
- " \"opencv-python\",\n",
- " \"ansitable\",\n",
- " \"mvtb-data\",\n",
- " \"tqdm\",\n",
- " \"requests\",\n",
- " \"ipywidgets\",\n",
- " # runtime dependencies of spatialmath-python and pgraph-python,\n",
- " # listed here because those two are installed with deps=False below\n",
- " \"numpy\",\n",
- " \"scipy\",\n",
- " \"matplotlib\",\n",
- " \"typing_extensions\",\n",
- " ]\n",
- " )\n",
- " # spatialmath-python <= 1.1.18 lists pre-commit (a dev tool) as a runtime\n",
- " # dependency; its virtualenv requires packaging>=26.3, which conflicts with\n",
- " # the packaging 24.2 built into Pyodide, so a normal resolve fails.\n",
- " # pgraph-python depends on spatialmath-python, so it needs the same\n",
- " # treatment. Remove once a spatialmath release without that dependency is\n",
- " # out (rai-opensource/spatialmath-python#250) and install both normally.\n",
- " await micropip.install(\n",
- " [\"spatialmath-python\", \"pgraph-python\"],\n",
- " deps=False,\n",
- " )\n",
- " import cv2 # noqa: F401 - force cv2 into module registry before toolbox import\n",
+ "def _older(version: str, required: str) -> bool:\n",
+ " try:\n",
+ " from packaging.version import InvalidVersion, Version\n",
+ " return Version(version) < Version(required)\n",
+ " except (ImportError, InvalidVersion):\n",
+ " return False\n",
"\n",
- " wheels = sorted(Path(\"/pypi\").glob(\"machinevision_toolbox_python-*.whl\"))\n",
- " if wheels:\n",
- " # Prefer the wheel bundled with this JupyterLite site. Relative,\n",
- " # not absolute: a leading slash resolves against the origin, not\n",
- " # this site's own base URL (a GitHub Pages project subpath).\n",
- " await micropip.install(f\"pypi/{wheels[-1].name}\", deps=False)\n",
- " else:\n",
- " # Fall back to PyPI when running outside the published site layout.\n",
- " await micropip.install(\"machinevision-toolbox-python\", deps=False)\n",
- " where, colab = \"in browser\", False\n",
+ "async def ensure_installed(extras: tuple[str, ...] | list[str]=(), packages: tuple[str, ...] | list[str]=(), min_version: str | None=None) -> bool:\n",
+ " if sys.platform == 'emscripten':\n",
+ " try:\n",
+ " import piplite\n",
+ " install = piplite.install\n",
+ " except ImportError:\n",
+ " import micropip\n",
+ " install = micropip.install\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " for name in JL_NO_DEPS:\n",
+ " await install(name, deps=False)\n",
+ " for name in JL_PACKAGES:\n",
+ " await install(name)\n",
+ " for extra in extras:\n",
+ " for name in JL_EXTRAS.get(extra, []):\n",
+ " await install(name)\n",
+ " for name in packages:\n",
+ " await install(name)\n",
+ " await install(PACKAGE, deps=not JL_PACKAGE_NO_DEPS)\n",
+ " where, colab = ('in browser', False)\n",
" else:\n",
" try:\n",
- " import google.colab # noqa: F401\n",
+ " import google.colab\n",
" except ImportError:\n",
- " where, colab = \"locally\", False\n",
+ " where, colab = ('locally', False)\n",
" else:\n",
- " print(\"Installing machinevision-toolbox-python...\")\n",
- " subprocess.run(\n",
- " [\n",
- " sys.executable,\n",
- " \"-m\",\n",
- " \"pip\",\n",
- " \"install\",\n",
- " \"-q\",\n",
- " \"machinevision-toolbox-python\",\n",
- " ],\n",
- " check=True,\n",
- " )\n",
- " where, colab = \"on Colab\", True\n",
- "\n",
- " import cv2\n",
- "\n",
- " import machinevisiontoolbox\n",
- "\n",
- " version = getattr(machinevisiontoolbox, \"__version__\", \"unknown\")\n",
- " opencv_version = getattr(cv2, \"__version__\", \"unknown\")\n",
- " print(f\"Running {where} using MVTB v{version} with OpenCV {opencv_version}\")\n",
+ " print(f'Installing {PACKAGE}, this takes a short time...', flush=True)\n",
+ " requirement = PACKAGE\n",
+ " if extras:\n",
+ " requirement += '[' + ','.join(extras) + ']'\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', requirement] + list(packages) + COLAB_PACKAGES, check=True)\n",
+ " try:\n",
+ " from matplotlib.backends import backend_registry\n",
+ " except ImportError:\n",
+ " pass\n",
+ " else:\n",
+ " clear = getattr(backend_registry, '_clear', None)\n",
+ " if clear is not None:\n",
+ " clear()\n",
+ " from google.colab import output\n",
+ " output.enable_custom_widget_manager()\n",
+ " where, colab = ('on Colab', True)\n",
+ " import importlib\n",
+ " module = importlib.import_module(IMPORT_NAME)\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " if colab and min_version is not None and _older(version, min_version) and GIT_URL:\n",
+ " print(f'{PACKAGE} {version} on PyPI is older than {min_version}, installing from GitHub...')\n",
+ " subprocess.run([sys.executable, '-m', 'pip', 'install', '-q', '--force-reinstall', '--no-deps', f'{PACKAGE} @ git+{GIT_URL}@main'], check=True)\n",
+ " importlib.invalidate_caches()\n",
+ " version = _version_of(PACKAGE, module)\n",
+ " where += ', development version from GitHub'\n",
+ " if not colab and where == 'locally':\n",
+ " import importlib.metadata\n",
+ " for name in packages:\n",
+ " try:\n",
+ " importlib.metadata.version(name)\n",
+ " except importlib.metadata.PackageNotFoundError:\n",
+ " print(f'This notebook needs {name}: pip install {name}')\n",
+ " if min_version is not None and where in ('locally', 'on Colab') and _older(version, min_version):\n",
+ " print(f'This notebook needs {PACKAGE} {min_version} or later: pip install -U {PACKAGE}')\n",
+ " print(f'Running {where} using {PACKAGE} v{version}')\n",
" return colab\n",
"\n",
"COLAB = await ensure_installed()\n"
@@ -226,7 +223,7 @@
"source": [
"## Colour planes\n",
"\n",
- "Access individual colour planes by name \u2014 the toolbox tracks the colour order so\n",
+ "Access individual colour planes by name — the toolbox tracks the colour order so\n",
"you never need to worry about BGR vs RGB."
]
},
@@ -309,6 +306,11 @@
}
],
"metadata": {
+ "kernelspec": {
+ "display_name": "Python 3",
+ "language": "python",
+ "name": "python3"
+ },
"language_info": {
"name": "python"
}
diff --git a/docs/notebooks/sync_bootstrap.py b/docs/notebooks/sync_bootstrap.py
deleted file mode 100644
index b209ab96..00000000
--- a/docs/notebooks/sync_bootstrap.py
+++ /dev/null
@@ -1,129 +0,0 @@
-#!/usr/bin/env python
-"""Regenerate the bootstrap cell in every notebook from _mvtb_nb_bootstrap.py.
-
-Every notebook in this folder carries its own copy of the environment-bootstrap
-logic, since Google Colab only fetches the single .ipynb file it's opened from and
-can't see sibling files. That copy is machine-generated from _mvtb_nb_bootstrap.py,
-the single source of truth -- see README.md for the full explanation.
-
-Usage:
- python sync_bootstrap.py regenerate any notebook that's out of date
- python sync_bootstrap.py --check report only, exit 1 if anything's out of date
- python sync_bootstrap.py FILE ... only consider the given notebook(s)
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from pathlib import Path
-
-MARKER = "# MVTB_BOOTSTRAP_CELL"
-GENERATED_HEADER = (
- f"{MARKER} -- sets up the environment (Colab / JupyterLite / local install); "
- "click to expand. Generated from docs/notebooks/_mvtb_nb_bootstrap.py by "
- "sync_bootstrap.py -- do not hand-edit.\n"
-)
-# Folds the cell's code by default (VS Code and JupyterLab both honour this) --
-# a reader sees the one-line header above and the printed status line below,
-# not the boilerplate, unless they choose to expand it.
-FOLDED_METADATA = {"jupyter": {"source_hidden": True}}
-
-HERE = Path(__file__).resolve().parent
-TEMPLATE_PATH = HERE / "_mvtb_nb_bootstrap.py"
-
-
-def generated_source(template: str) -> list[str]:
- """Build the full source (as nbformat-style lines) for the bootstrap cell."""
- body = f"{GENERATED_HEADER}\n{template.rstrip()}\n\nCOLAB = await ensure_installed()\n"
- lines = body.splitlines(keepends=True)
- return lines
-
-
-def cell_source_text(cell: dict) -> str:
- source = cell.get("source", [])
- return "".join(source) if isinstance(source, list) else source
-
-
-def is_bootstrap_cell(cell: dict) -> bool:
- if cell.get("cell_type") != "code":
- return False
- text = cell_source_text(cell)
- first_line = text.splitlines()[0].strip() if text.strip() else ""
- return first_line.startswith(MARKER)
-
-
-def process_notebook(path: Path, template: str, fix: bool) -> bool:
- """Check (and optionally fix) one notebook's bootstrap cell.
-
- :returns: True if the notebook's bootstrap cell was (or would be) changed.
- """
- with path.open("r", encoding="utf-8") as f:
- nb = json.load(f)
-
- changed = False
- for cell in nb.get("cells", []):
- if not is_bootstrap_cell(cell):
- continue
-
- desired_source = generated_source(template)
- current_source = cell.get("source", [])
- if not isinstance(current_source, list):
- current_source = [current_source]
-
- current_jupyter_metadata = cell.get("metadata", {}).get("jupyter", {})
- desired_jupyter_metadata = FOLDED_METADATA["jupyter"]
-
- if current_source != desired_source or current_jupyter_metadata != desired_jupyter_metadata:
- changed = True
- if fix:
- cell["source"] = desired_source
- cell.setdefault("metadata", {})["jupyter"] = dict(desired_jupyter_metadata)
- break
-
- if changed and fix:
- with path.open("w", encoding="utf-8") as f:
- json.dump(nb, f, indent=1)
- f.write("\n")
-
- return changed
-
-
-def main() -> int:
- parser = argparse.ArgumentParser(description=__doc__)
- parser.add_argument(
- "--check",
- action="store_true",
- help="report out-of-date notebooks without modifying them; exit 1 if any found",
- )
- parser.add_argument(
- "files",
- nargs="*",
- type=Path,
- help="only consider these notebooks (default: every *.ipynb in this folder)",
- )
- args = parser.parse_args()
-
- template = TEMPLATE_PATH.read_text(encoding="utf-8")
- fix = not args.check
- notebooks = [p.resolve() for p in args.files] if args.files else sorted(HERE.glob("*.ipynb"))
-
- any_changed = False
- for nb_path in notebooks:
- changed = process_notebook(nb_path, template, fix=fix)
- if changed:
- any_changed = True
- rel = nb_path.relative_to(HERE.parent.parent)
- if fix:
- print(f"{rel}: bootstrap cell out of date, regenerating")
- else:
- print(f"{rel}: bootstrap cell out of date")
-
- if args.check and any_changed:
- return 1
- return 0
-
-
-if __name__ == "__main__":
- sys.exit(main())
diff --git a/pyproject.toml b/pyproject.toml
index 58f35181..83c47738 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -41,7 +41,7 @@ dependencies = [
"pillow",
"opencv-python>=4.5,<6.0.0",
"opencv-contrib-python>=4.5,<6.0.0",
- "spatialmath-python",
+ "spatialmath-python>=1.1.19",
"pgraph-python>=0.6.4",
"ansitable",
"mvtb-data",
diff --git a/tests/test_notebook_bootstrap.py b/tests/test_notebook_bootstrap.py
deleted file mode 100644
index 806dd302..00000000
--- a/tests/test_notebook_bootstrap.py
+++ /dev/null
@@ -1,165 +0,0 @@
-"""Tests for the notebook bootstrap-cell generator and output-clearing scripts.
-
-These exercise the pure notebook-JSON manipulation logic in
-docs/notebooks/sync_bootstrap.py and docs/notebooks/clear_outputs.py directly, not
-via subprocess -- what can't be tested this way (whether the generated cell's
-*content* actually installs correctly in Colab/JupyterLite/locally) needs a real
-run in each of those environments, which is a separate, non-pytest concern.
-"""
-
-import importlib.util
-import json
-import sys
-from pathlib import Path
-
-NOTEBOOKS_DIR = Path(__file__).resolve().parent.parent / "docs" / "notebooks"
-
-
-def _load_module(name: str, path: Path):
- spec = importlib.util.spec_from_file_location(name, path)
- module = importlib.util.module_from_spec(spec)
- sys.modules[name] = module
- spec.loader.exec_module(module)
- return module
-
-
-sync_bootstrap = _load_module("_sync_bootstrap", NOTEBOOKS_DIR / "sync_bootstrap.py")
-clear_outputs = _load_module("_clear_outputs", NOTEBOOKS_DIR / "clear_outputs.py")
-
-
-def _write_notebook(path: Path, cells: list[dict]) -> None:
- nb = {
- "cells": cells,
- "metadata": {},
- "nbformat": 4,
- "nbformat_minor": 5,
- }
- path.write_text(json.dumps(nb, indent=1) + "\n", encoding="utf-8")
-
-
-def _code_cell(source: str, outputs=None, execution_count=None) -> dict:
- return {
- "cell_type": "code",
- "metadata": {},
- "execution_count": execution_count,
- "outputs": outputs or [],
- "source": source.splitlines(keepends=True),
- }
-
-
-# --- sync_bootstrap.py -------------------------------------------------------
-
-
-def test_is_bootstrap_cell_detects_marker():
- marked = _code_cell(f"{sync_bootstrap.MARKER}\nprint('hi')\n")
- unmarked = _code_cell("print('hi')\n")
- markdown = {"cell_type": "markdown", "source": [f"{sync_bootstrap.MARKER}\n"]}
-
- assert sync_bootstrap.is_bootstrap_cell(marked)
- assert not sync_bootstrap.is_bootstrap_cell(unmarked)
- assert not sync_bootstrap.is_bootstrap_cell(markdown)
-
-
-def test_generated_source_embeds_template_and_call():
- template = "async def ensure_installed():\n return False\n"
- lines = sync_bootstrap.generated_source(template)
- text = "".join(lines)
-
- assert text.startswith(sync_bootstrap.MARKER)
- assert "async def ensure_installed():" in text
- assert text.rstrip().endswith("COLAB = await ensure_installed()")
-
-
-def test_process_notebook_check_mode_reports_without_writing(tmp_path):
- nb_path = tmp_path / "demo.ipynb"
- stale_cell = _code_cell(f"{sync_bootstrap.MARKER}\n# stale content\n")
- _write_notebook(nb_path, [stale_cell])
- before = nb_path.read_text(encoding="utf-8")
- template = "async def ensure_installed():\n return False\n"
-
- changed = sync_bootstrap.process_notebook(nb_path, template=template, fix=False)
-
- assert changed is True
- assert nb_path.read_text(encoding="utf-8") == before # untouched
-
-
-def test_process_notebook_fix_mode_rewrites_and_is_idempotent(tmp_path):
- nb_path = tmp_path / "demo.ipynb"
- stale_cell = _code_cell(f"{sync_bootstrap.MARKER}\n# stale content\n")
- _write_notebook(nb_path, [stale_cell])
- template = "async def ensure_installed():\n return False\n"
-
- changed = sync_bootstrap.process_notebook(nb_path, template=template, fix=True)
- assert changed is True
-
- # A second pass over the now-regenerated file should find nothing to do.
- changed_again = sync_bootstrap.process_notebook(nb_path, template=template, fix=True)
- assert changed_again is False
-
- nb = json.loads(nb_path.read_text(encoding="utf-8"))
- cell_text = "".join(nb["cells"][0]["source"])
- assert "async def ensure_installed():" in cell_text
-
-
-def test_process_notebook_without_marker_cell_is_a_no_op(tmp_path):
- nb_path = tmp_path / "demo.ipynb"
- _write_notebook(nb_path, [_code_cell("import numpy as np\n")])
-
- changed = sync_bootstrap.process_notebook(nb_path, template="whatever", fix=True)
-
- assert changed is False
-
-
-# --- clear_outputs.py ---------------------------------------------------------
-
-
-def test_clear_cell_strips_output_and_execution_count():
- cell = _code_cell("print(1)\n", outputs=[{"output_type": "stream", "text": "1\n"}], execution_count=3)
-
- changed = clear_outputs.clear_cell(cell)
-
- assert changed is True
- assert cell["outputs"] == []
- assert cell["execution_count"] is None
-
-
-def test_clear_cell_leaves_clean_cell_untouched():
- cell = _code_cell("print(1)\n")
-
- changed = clear_outputs.clear_cell(cell)
-
- assert changed is False
-
-
-def test_clear_cell_ignores_markdown_cells():
- cell = {"cell_type": "markdown", "source": ["# Title\n"]}
-
- assert clear_outputs.clear_cell(cell) is False
-
-
-def test_process_notebook_fix_mode_clears_and_is_idempotent(tmp_path):
- nb_path = tmp_path / "demo.ipynb"
- dirty_cell = _code_cell("print(1)\n", outputs=[{"output_type": "stream", "text": "1\n"}], execution_count=3)
- _write_notebook(nb_path, [dirty_cell])
-
- changed = clear_outputs.process_notebook(nb_path, fix=True)
- assert changed is True
-
- changed_again = clear_outputs.process_notebook(nb_path, fix=True)
- assert changed_again is False
-
- nb = json.loads(nb_path.read_text(encoding="utf-8"))
- assert nb["cells"][0]["outputs"] == []
- assert nb["cells"][0]["execution_count"] is None
-
-
-def test_process_notebook_check_mode_does_not_write(tmp_path):
- nb_path = tmp_path / "demo.ipynb"
- dirty_cell = _code_cell("print(1)\n", outputs=[{"output_type": "stream", "text": "1\n"}], execution_count=3)
- _write_notebook(nb_path, [dirty_cell])
- before = nb_path.read_text(encoding="utf-8")
-
- changed = clear_outputs.process_notebook(nb_path, fix=False)
-
- assert changed is True
- assert nb_path.read_text(encoding="utf-8") == before