MulimgViewer: a Python multi-image viewer for side-by-side comparison and stitching
MulimgViewer is a multi-image viewer that can open multiple images in one interface, which is convenient for image comparison and image stitching.
At a glance
- What is it?
- MulimgViewer opens many images in one interface so you can compare, select, zoom and stitch them. The README itself warns that the current master branch has many bugs, which is the first thing to weigh before adopting it.
- Who is it for?
- Adopt MulimgViewer if you routinely compare large image sets by eye (paired datasets, model outputs, dataset triage) and can tolerate a GUI tool whose README tells you to check out commit 0d6e6a5570eeb6076342590078516de212cb3375 instead of master. Do not adopt it if you need an actively released, commercially licensed product, or if your comparison work is scriptable in a few lines of Pillow, because then the GUI adds nothing.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 33 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem MulimgViewer addresses: comparing images one window at a time
Standard image viewers show one file. When you need to compare a hundred outputs from two model versions, or check a paired dataset for alignment, you end up alt-tabbing between windows and losing track of which file you are looking at. MulimgViewer loads images from multiple folders and displays them side by side in a single interface, which the README describes as being for image comparison and screening. The README's own example is browsing the CelebA database of 202,599 images: at 1000 images per screen, that is a little over 200 clicks. The intended audience is people doing visual inspection at volume: computer vision researchers checking generated or restored images, anyone curating a dataset, and anyone who needs a paper-ready comparison figure. The topics list on the repository (computer-vision, deep-learning, image-comparison, image-stitching) matches that audience rather than general photo management.
How the interface works: input modes, the parallel selection mechanism and stitching
The core data flow is folder-driven. You point the tool at one or more input directories, and it renders the images in a grid; navigation moves through the set in batches. Two input modes are named in the README: Sequential, where you pick one input folder, and the parallel modes, Parallel auto and Parallel manual. The README states that parallel selection requires turning off Parallel+Sequential. Selection writes files out: by default it copies, and checking MoveFile switches the operation to a cut. That copy-versus-move default matters, because a mis-click in move mode relocates originals out of your dataset rather than duplicating them. Zooming is the other half of the mechanism. You can draw a box anywhere with a held left mouse button, and a right-click creates an additional box, so several regions magnify at once. Stitching is built on the same rendering path: the README says the tool supports horizontal and vertical concatenation, automatic stitching and saving, and parallel zoom. For paired-data browsing and for one-click generation of a comparison figure there are dedicated documented workflows, including displaying titles and choosing where the zoom box sits.
Getting it running and the config keys that control output
The README points to two documentation pages rather than inlining commands: a quick start page and a download and install page under mulimgviewer.readthedocs.io. The installation specifics are not reproduced in the README text supplied here, so the exact pip or source command cannot be confirmed from this material; treat the install page as the source of truth. What the README does spell out is the option vocabulary, and that is where the tool's real behaviour lives. AutoSaveAll enables automatic saving of every rendered view. TruthResolution sets a fixed output size, and the README's batch-resize recipe is Sequential input mode, a chosen output directory, AutoSaveAll checked, TruthResolution set to something like 256,256, then the save button. NumPerimg controls how many images are composited into one when OneImg is checked. Gap(x,y) takes a per-slot list, and Gap(x,y)=*,*,0,*,* removes spacing at one position. Scale is written in the README as Scale=-1,-1 for the middle-bottom zoom-box placement, with 1.5,1.5 suggested for other placements. These keys are the tool's actual API surface: there is no scriptable configuration file described, so reproducing a comparison figure later means reproducing the GUI state.
The bug warning in the README is the first thing to evaluate
The README opens with a notice, in Chinese, stating that the current latest code has a large number of bugs and that anyone wanting the new features should use a specific commit, 0d6e6a5570eeb6076342590078516de212cb3375, instead. This is unusually candid and it changes how you should read everything else. The last tagged release listed is v3.9.7 from May 2022, while the repository's last push is dated 2026, so there is a multi-year gap between the packaged release and whatever is on master. A user following the install docs may end up on code the maintainer has publicly disclaimed. That is a real failure mode: features described in the documentation may be present in one commit and broken in another, and without a scripted test suite described in this material there is no way to know which. The practical consequence is that you should pin a commit rather than track master, and you should verify the specific features you need against that pin before building any workflow around them.
Where it is the wrong tool, and what to use instead
MulimgViewer is a GUI. If your comparison is deterministic and repeatable, a short Pillow or OpenCV script that tiles a directory into a contact sheet gives you version control, a diffable output and no dependence on a pinned commit. The difference in approach is not cosmetic: MulimgViewer keeps state in the interface (which boxes are open, where they sit, what the scale is), while a script keeps state in source code. For a one-off figure that is fine; for a pipeline that runs on every new model checkpoint, the script wins. ImageMagick's montage is the other obvious alternative, and it is a command-line tool whose output is reproducible from an argument list, which MulimgViewer deliberately is not. The trade-off runs the other way for interactive triage: montage will not let you draw a zoom box on a region that looks wrong, right-click a second box, and flip through a thousand images deciding keep or discard. MulimgViewer's parallel selection with copy-by-default is genuinely faster than shelling out per file, and no command-line tool described in this material replaces that interaction.
Licence, commercial use and the extra terms
The project is GPL-3.0, and the README's BibTeX entry records the licence as GPL-3. The README then adds extra terms: personal use is permitted, and commercial use requires contacting liujiawei18@mails.ucas.ac.cn. That combination is worth pausing on, because GPL-3.0 already grants commercial use rights to anyone who receives the software under it, and an added restriction sits awkwardly against that grant. This is not a legal opinion and should not be read as one; if you are deploying MulimgViewer inside a company, the honest step is to read the GPL-3.0 text and the extra terms together and decide whether you need the maintainer's written permission. For an individual researcher the practical effect is close to nil. For a team, the added clause is a reason to ask before standardising on the tool, especially since the same README tells you the current code is buggy, which makes the commercial path harder to justify on support grounds.
Maintenance cost and what to check before committing to it
The release history is the clearest signal here. Three tags are listed, v3.9.5 through v3.9.7, spanning August 2021 to May 2022. The repository is not archived and shows a push in 2026, but no release accompanies that push in the material supplied, and the README's own notice says the current code is buggy. Upgrading is therefore not a routine operation: moving from a tagged release to master means moving to code the maintainer has flagged, and moving between commits means re-verifying every config key you rely on. Budget for pinning a commit, recording the exact GUI settings that produced each figure, and re-checking after any change. The remote-mount examples in the README (nautilus with an sftp URL on Ubuntu, SSHFS-Win with a path like \\sshfs\user@ip!port on Windows 10) mean the tool inherits your filesystem's behaviour, so a slow or dropped mount shows up as a stalled viewer rather than a clear error. Before adopting: confirm the commit, confirm the features, and confirm the licence position for your use.
Editorial conclusion
Adopt MulimgViewer if you routinely compare large image sets by eye (paired datasets, model outputs, dataset triage) and can tolerate a GUI tool whose README tells you to check out commit 0d6e6a5570eeb6076342590078516de212cb3375 instead of master. Do not adopt it if you need an actively released, commercially licensed product, or if your comparison work is scriptable in a few lines of Pillow, because then the GUI adds nothing. Verify three things first: which commit you are actually running, whether your use is commercial (the README routes commercial use to liujiawei18@mails.ucas.ac.cn rather than to the GPL grant), and whether the config keys you depend on (NumPerimg, TruthResolution, Gap, Scale) behave the same in that commit as in the docs.
Community notes