Skip to content

Windows: one-line install, tests pass on Windows; standalone install needs [pyqt6] - #46

Merged
hongquanli merged 3 commits into
mainfrom
docs/windows-install
Nov 8, 2026
Merged

hongquanli merged 3 commits into
mainfrom
docs/windows-install

Conversation

@hongquanli

@hongquanli hongquanli commented Nov 8, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Windows install in one line, a fix to the standalone install instructions, and a test suite that passes on Windows.

One-line Windows install (README)

git clone https://github.com/Cephla-Lab/ndviewer_light; cd ndviewer_light; py -3 -m venv .venv; .\.venv\Scripts\python -m pip install ".[pyqt6]"; .\.venv\Scripts\python create_shortcut.py

This clones, creates a venv inside the clone, installs with the [pyqt6] extra, and puts an NDViewer Light shortcut on the Desktop. The README also covers how to update and how to run from a terminal. It explains why the command uses py: on a fresh Windows, python is a stub that opens the Microsoft Store.

Tested verbatim (except that the clone came from this branch) in a fresh PowerShell on Windows 11 with Python 3.10:

  • installed in 72 s;
  • the shortcut points at the new venv's ndviewer-light.exe;
  • the fresh install (PyQt6 6.12, ndv 0.5.0) opens a 1772-field OME-Zarr plate and steps a slider in ~50 ms.

Standalone install was missing a Qt binding

The standalone snippet ran pip3 install .. Since #40, qtpy is the only Qt dependency, so a fresh install following the README had no binding and could not open a window. It now runs pip3 install ".[pyqt6]", which is what the Requirements section already says.

create_shortcut.py targets the venv it is run with

The script looked up ndviewer-light on PATH only. Running it with a venv's python without activating the venv, as the one-liner does, therefore fell back to python.exe -m ndviewer_light; if another ndviewer-light was on PATH, it picked that one instead. It now checks next to sys.executable first, then PATH, then falls back to python -m. tests/test_create_shortcut.py covers that order.

Tests pass on Windows as-is

  • test_existing_field_without_metadata_is_broken and test_broken_fov_fails_the_load expected B/3/0 in error messages. Those messages name the field by its filesystem path, which is B\3\0 on Windows. The expected fragment is now built with pathlib, so the field is still checked on every OS.
  • test_3d_scales.py and test_channel_names.py read core.py with the locale encoding, which is cp1252 on Windows and fails on its non-ASCII characters. They now read it as UTF-8.
  • README (Development) gains the PowerShell command for the real-GL run. No Windows caveats are needed any more.

Run as the README says, on Windows 11 / Python 3.10 / PyQt5: offscreen 312 passed, 3 skipped; real GL (QT_QPA_PLATFORM=windows NDVL_REAL_GL=1) 315 passed. black --check . and ruff check are clean.

🤖 Generated with Claude Code

hongquanli and others added 2 commits November 7, 2026 20:28
…extra

- README: a PowerShell one-liner for Windows (clone, venv, install with the
  [pyqt6] extra, desktop shortcut), with how to update and run from a
  terminal and why it uses `py` (a fresh Windows's `python` is a Store stub).
- README: the standalone snippet installed `.` without a Qt binding; since
  #40 qtpy is the only Qt dependency, so it could not open a window. It now
  installs ".[pyqt6]", as the Requirements section already says.
- README: Windows test commands (PYTHONUTF8 for two tests that read source
  files with the default encoding; QT_QPA_PLATFORM=windows for real GL) and
  the two tests that fail on Windows only (they expect `/` in paths).
- create_shortcut.py: prefer the `ndviewer-light` next to the running
  interpreter over the first one on PATH, so running the script with a
  venv's python (as the one-liner does, without activating it) points the
  shortcut at that venv's launcher instead of falling back to
  `python -m ndviewer_light`. tests/test_create_shortcut.py covers the
  order: next to the interpreter, then PATH, then `python -m`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- test_existing_field_without_metadata_is_broken and
  test_broken_fov_fails_the_load expected `B/3/0` in error messages, which
  name the field by its filesystem path (`B\3\0` on Windows). They now
  build the expected fragment with pathlib, so the message is still
  checked for the field on every OS.
- test_3d_scales.py and test_channel_names.py read core.py with the locale
  encoding (cp1252 on Windows), which fails on its non-ASCII characters;
  they now read it as UTF-8.
- README: drop the PYTHONUTF8 step and the known-failures note.

Windows, run as the README says: offscreen 312 passed / 3 skipped; real GL
315 passed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@hongquanli hongquanli changed the title docs: one-line Windows install; standalone install needs the [pyqt6] extra Windows: one-line install, tests pass on Windows; standalone install needs [pyqt6] Nov 8, 2026
…directory

shutil.which(path=...) on Windows Python <= 3.11 still searches the current
directory first, so a stray ndviewer-light.exe there won over the running
interpreter's sibling launcher. Check the sibling path directly, then fall
back to PATH, then to `python -m ndviewer_light`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@hongquanli
hongquanli merged commit ccc7517 into main Nov 8, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant