feat(notebooks): migrate notebooks to the bootstrap cell, fix real-browser-found bugs

.github/workflows/docs.yml

@@ -108,7 +108,7 @@ jobs:
                   new_lines = []
                   changed = False
                   for line in lines:
-                      if line.strip() == "%matplotlib ipympl":
+                      if line.strip() in ("%matplotlib ipympl", "%matplotlib widget"):
                           newline = "\n" if line.endswith("\n") else ""
                           new_lines.append(f"%matplotlib inline{newline}")
                           changed = True

docs/lite/jupyter-lite.json

@@ -1,6 +1,6 @@
 {
     "jupyter-lite-schema-version": 0,
     "jupyter-config-data": {
-        "appUrl": "./lab/index.html?path=files/index.ipynb"
+        "appUrl": "./lab/index.html?path=index.ipynb"
     }
 }

docs/notebooks/IBVS.ipynb

@@ -27,6 +27,99 @@
     "If you're running locally you need to have these packages installed.  If you're running on CoLab we have to first install machinevisiontoolbox which is not preinstalled, this will be a bit slow."
    ]
   },
+  {
+   "cell_type": "code",
+   "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",
+    "\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",
+    "                \"spatialmath-python\",\n",
+    "                \"pgraph-python\",\n",
+    "                \"ansitable\",\n",
+    "                \"mvtb-data\",\n",
+    "                \"tqdm\",\n",
+    "                \"requests\",\n",
+    "                \"ipywidgets\",\n",
+    "            ]\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",
+    "    else:\n",
+    "        try:\n",
+    "            import google.colab  # noqa: F401\n",
+    "        except ImportError:\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",
+    "    return colab\n",
+    "\n",
+    "COLAB = await ensure_installed()\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -35,14 +128,6 @@
    },
    "outputs": [],
    "source": [
-    "try:\n",
-    "    import google.colab\n",
-    "    print('Running on CoLab')\n",
-    "    %pip install machinevision-toolbox-python\n",
-    "    COLAB = True\n",
-    "except:\n",
-    "    COLAB = False\n",
-    "    \n",
     "import numpy as np\n",
     "import math\n",
     "\n",

docs/notebooks/_mvtb_nb_bootstrap.py

@@ -31,14 +31,17 @@
                 "mvtb-data",
                 "tqdm",
                 "requests",
+                "ipywidgets",
             ]
         )
         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.
-            await micropip.install(wheels[-1].as_posix(), deps=False)
+            # 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)
@@ -63,8 +66,11 @@
             )
             where, colab = "on Colab", True
 
+    import cv2
+
     import machinevisiontoolbox
 
     version = getattr(machinevisiontoolbox, "__version__", "unknown")
-    print(f"Running {where} using MVTB v{version}")
+    opencv_version = getattr(cv2, "__version__", "unknown")
+    print(f"Running {where} using MVTB v{version} with OpenCV {opencv_version}")
     return colab

docs/notebooks/calibration.ipynb

@@ -18,18 +18,103 @@
   },
   {
    "cell_type": "code",
+   "id": "mvtb-bootstrap-cell",
+   "metadata": {
+    "jupyter": {
+     "source_hidden": true
+    }
+   },
    "execution_count": null,
-   "metadata": {},
    "outputs": [],
    "source": [
-    "try:\n",
-    "    import google.colab\n",
-    "    print('Running on CoLab')\n",
-    "    %pip install machinevision-toolbox-python\n",
-    "    COLAB = True\n",
-    "except:\n",
-    "    COLAB = False\n",
+    "# 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",
+    "\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",
+    "                \"spatialmath-python\",\n",
+    "                \"pgraph-python\",\n",
+    "                \"ansitable\",\n",
+    "                \"mvtb-data\",\n",
+    "                \"tqdm\",\n",
+    "                \"requests\",\n",
+    "                \"ipywidgets\",\n",
+    "            ]\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",
+    "    else:\n",
+    "        try:\n",
+    "            import google.colab  # noqa: F401\n",
+    "        except ImportError:\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",
+    "    return colab\n",
+    "\n",
+    "COLAB = await ensure_installed()\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
     "from machinevisiontoolbox import *\n",
     "import numpy as np\n",
     "np.set_printoptions(linewidth=120, formatter={'float': lambda x: f\"{x:8.4g}\" if abs(x) > 1e-10 else f\"{0:8.4g}\"})"

docs/notebooks/camera.ipynb

@@ -29,6 +29,99 @@
     "If you're running locally you need to have these packages installed.  If you're running on CoLab we have to first install machinevisiontoolbox which is not preinstalled, this will be a bit slow."
    ]
   },
+  {
+   "cell_type": "code",
+   "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",
+    "\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",
+    "                \"spatialmath-python\",\n",
+    "                \"pgraph-python\",\n",
+    "                \"ansitable\",\n",
+    "                \"mvtb-data\",\n",
+    "                \"tqdm\",\n",
+    "                \"requests\",\n",
+    "                \"ipywidgets\",\n",
+    "            ]\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",
+    "    else:\n",
+    "        try:\n",
+    "            import google.colab  # noqa: F401\n",
+    "        except ImportError:\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",
+    "    return colab\n",
+    "\n",
+    "COLAB = await ensure_installed()\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -37,14 +130,6 @@
    },
    "outputs": [],
    "source": [
-    "try:\n",
-    "    import google.colab\n",
-    "    print('Running on CoLab')\n",
-    "    %pip install machinevision-toolbox-python\n",
-    "    COLAB = True\n",
-    "except:\n",
-    "    COLAB = False\n",
-    "    \n",
     "%matplotlib inline\n",
     "\n",
     "import numpy as np\n",