MulimgViewer points new users at one commit because the default branch is buggy

The first line of the README is a warning and a commit hash

The boldest text on the page is a warning, and it appears before the project name is even explained. It says that the newest code contains many bugs, and that anyone who wants to try the new features should use the code at a specific commit, given as a full forty character hash in a GitHub tree URL.

That is an unusual instruction, and worth reading carefully. The maintainer is not pointing at a release, a branch or a tag. It is a commit, so there is no version name to put in a requirements file and no way to check whether you have the version the warning means. It is also a pointer backwards: the page itself frames that commit as the place to experience new features, which means the branch people clone by default is worse than a known older state.

The release history is consistent with a long gap. The three newest tags are v3.9.5 from 2021-08-27, v3.9.6 from 2021-11-23 and v3.9.7 from 2022-05-16, while the most recent push is dated 2026-08-13. So there are years of commits with no tagged release, and the README offers a hash where a version would normally go.

GPL-3.0 is stated, then an extra clause is added underneath it

The licence section has two parts. The first states GPL-3.0 and links to the GNU licence text. The second is headed additional terms, and has two lines: personal use is permitted, and commercial use requires contacting an address at the University of Chinese Academy of Sciences.

The build metadata agrees with the first half and says nothing about the second. The project metadata declares `text = "GPL v3"`, the classifier reads GNU General Public License v3, and the BibTeX entry that the page asks researchers to cite records `license = {GPL-3}`.

That citation entry also records a different name than the project metadata does. The BibTeX author is Liu, Jiawei, while the project author is nachifur with a QQ mail address, and the commercial contact is a third address. So a reader has one licence name, one copyright name in the citation, another in the package metadata, and a rider on commercial use that none of the metadata mentions.

Nothing here settles how those two statements relate. That is a question for whoever ships the tool, and the honest move is to ask before using it commercially rather than assume which text wins.

The requirements list ffmpeg-python and then asks for ffmpeg separately

The dependency file is short, and one of its comments matters more than the list:

ffmpeg-python
imageio
# runtime
numpy
piexif
Pillow

# tests (optional)
pytest-shutil
requests
wxPython

# NOTE: 需要系统里有 FFmpeg 可执行文件；建议：
# conda install -c conda-forge ffmpeg

The comment says the system needs an FFmpeg executable present, and suggests installing it through conda-forge. So `ffmpeg-python` is a wrapper around a binary the package does not ship and pip cannot install, which makes the very first line of the dependency list a two step install.

The second surprise is where wxPython sits. This is a desktop viewer with a windowed interface, yet the GUI toolkit appears under the heading for optional test dependencies, alongside pytest-shutil and requests. The declared runtime set is numeric and image-shaped instead: numpy, Pillow, piexif for EXIF, imageio and the ffmpeg wrapper.

There is also a second requirements location in the tree, a `requirements/` directory beside the file above, so a plain pip install from one file may not be the whole story.

The Python floor is 3.7 and the classifier list stops at 3.11

The package metadata states `requires-python = ">= 3.7"`. The classifier list then enumerates Python 3.7, 3.8, 3.9, 3.10 and 3.11, for CPython and for PyPy, and stops. Nothing claims a newer interpreter, so on a current machine the floor is generous and the ceiling is unstated rather than enforced.

The status is honest in the same file: Development Status 3, Alpha. Keywords run to fifteen entries, from computer-vision and deep-learning through image-stitching and multiple-image-comparison, which reads like a list built for discoverability rather than for users.

The version and the dependency list are both declared dynamic, filled in at build time by setuptools_scm with setuptools-generate rather than written as literals. That connects directly to the release gap: with the version derived from source control metadata, a checkout with no reachable tag has no version to report, which is a good reason for the README to hand you a commit hash instead.

Intended audience is Developers, and the operating system classifiers cover Windows, POSIX, Unix and MacOS, matching the cross platform instructions further down the page.

Settings are named strings in the interface, and one name begins with an emoji

There is no configuration file in this project as far as the page shows. Everything is a labelled control in the window, and the README quotes the labels verbatim, which is how you learn they exist at all.

The selection workflow uses `Parallel auto` or `Parallel manual`, with `Parallel+Sequential` switched off, and copying by default unless you pick `MoveFile` to cut instead. The comparison figure workflow names a position, `middle bottom`, and a zoom field written with an emoji at the front of its name, whose value is given as `Scale=-1,-1` or, for other positions, something like `Scale=1.5,1.5`. Composing several images into one uses an `OneImg` checkbox, a `NumPerimg` count and a gap string, `Gap(x,y)=*,*,0,*,*`, where the zeroes remove the spacing.

The batch resize path is the most explicit: choose Sequential as the input mode, pick the input folder, choose an output directory, tick `AutoSaveAll`, set `TruthResolution` to a fixed size such as `256,256`, and click save.

The zoom names being emoji prefixed is a small but real usability fact. A field whose label starts with an emoji has to be selected from the interface rather than typed, and it will not survive a round trip through a script that reproduces the documented value literally.

The remote folder example writes stfp where the scheme should read sftp

Example six covers remote directories, and the premise is that you mount the server first and then pick the mounted path inside the viewer. Two platforms are given.

On Ubuntu the instruction is to use the file manager `nautilus` and connect with a URI written as `stfp://10.8.0.4`. The letters are transposed: the scheme is `sftp`, and as printed the URI will not work. It is a two character typo in the only command on the page, and it sits in the middle of an otherwise careful instruction.

On Windows the path is spelled out differently. Install WinFsp and SSHFS-Win, then fill the remote server address into the file explorer using a path shaped like `\\sshfs\user@ip!port`, with an exclamation mark separating the port from the rest.

The page asks readers to report dead hyperlinks through an issue tracker link, which is a reasonable request for a document with this many links. It does not ask for corrections to the prose itself, which is why a broken scheme and a translated sentence can sit here indefinitely.

The tree mixes Python, Nix, Ruby and Homebrew conventions

The root of the repository is wider than a Python package usually is. Besides the expected `pyproject.toml`, `requirements.txt`, `MulimgViewer.py` at the top level, `src/`, `docs/`, `examples/` and `assets/`, there is a `flake.nix` with a `flake.lock`, a `Brewfile`, a Ruby linter configuration in `.rubocop.yml`, and a file named `python-mulimgviewer.rb` that follows the Homebrew formula naming pattern.

That last one explains how a desktop Python application ends up installable through a package manager on macOS, and the flake files do the same job on Nix systems. Documentation infrastructure is present too, with `.readthedocs.yaml` matching the Read the Docs site, `CHANGELOG.md` and `CITATION.cff` for citation metadata.

The quality tooling is broad for a project of this size: a pre-commit configuration, yamllint, gitlint, a `.mailmap`, and a DeepSource configuration file. Dependencies also live in a `requirements/` directory next to `requirements.txt`, and the examples folder holds one script, `add_new_info_to_img.py`, plus an `input/` directory of sample files.

Mirrors exist in two places, a Gitee mirror for readers inside China and a mirror under the OpenCas organisation on GitHub, and the page also links a QQ group with a nine digit number for support.

Editorial conclusion

MulimgViewer fits researchers and annotators who have to look at thousands of frames or pairs, since the parallel selection, parallel zoom and one-click comparison figure are the reason the tool exists, and the wheel over a mounted SSH folder makes it usable on data that never lands on the laptop. It is not a fit for anyone who needs a predictable release, because the newest tag is v3.9.7 from 2022 while commits continue, and the project's own guidance for new features is a commit hash rather than a version. Two things to settle before you build on it. Read the licence page carefully, because it states GPL-3.0 and then adds a clause conditioning commercial use on contacting the author, and those are two different promises. And install FFmpeg yourself, since the Python package only wraps a binary it expects to find on the system.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. nachifur/MulimgViewer on GitHub
3. Project website
4. README
5. Releases