jcupitt / vipsdisp

Tiny libvips / gtk+4 image viewer

vipsdisp

This program displays an image with libvips and gtk4. This is supposed to be a slightly useful image viewer. It can display huge (many, many GB) images quickly and without using much memory. It supports many scientific and technical image formats, including TIFF, WEBP, JP2K, JXL, AVIF, HEIC, PNG, JPEG, SVS, MRXS, OpenEXR, GIF, PDF, SVG, FITS, Matlab, NIfTI, Analyze, etc. It supports pixel types from 1 bit mono to 128-bit double precision complex.

All of the UI can make finding the details of image display in the sourcecode difficult. See vipsdisp-tiny for a minimal example --- that's a libvips image viewer in about 300 lines of very commented C.

Screenshots

It all works, though see the TODO list below.

https://youtu.be/KSoBkO2_HtE

Install

This program is on flathub, see:

https://flathub.org/apps/org.libvips.vipsdisp

Just click "install", or enter:

flatpak install flathub org.libvips.vipsdisp

Features

• It supports many scientific and technical image formats, including TIFF, WEBP, JP2K, JXL, HEIC, AVIF, PNG, JPEG, SVS, MRXS, OpenEXR, GIF, PDF, SVG, FITS, Matlab, NIfTI, Analyze, etc. It supports many numeric pixel types, any number of image bands, many colour spaces.

• It doesn't need to keep the whole image in memory. It will only read parts that it needs for display, and it understands most pyramidal image formats. This means you can open and view huge images quickly.

• It has threaded, asynchronous display repaint, so pixels are computed in the background by a pool of workers. The interface stays live even under very heavy load.

• It keeps a sparse pyramid of computed tiles as textures on the GPU. Each frame, it computes the set of visible tiles, and then the GPU scales, positions and composites just those tiles to the screen. CPU load should be low (except for the background workers heh). Hold down i (for "in") or + to do a smooth zoom on the cursor. If you press "d" it toggles a debug display mode which shows the tiles being computed.

• Select Display control bar from the top-right menu and a useful set of visualization options appear. It supports four main display modes: Toilet roll (sorry), Multipage, Animated, and Pages as Bands.

• In Toilet roll mode, a multi-page image is presented as a tall, thin strip of images. In Multipage, you see a single page at a time, with a page-select spinner (you can also use the crtl-< and ctrl-> keys to flip pages). In animated mode, pages flip automatically on a timeout. In pages-as-bands mode, many-page single-band images (eg. OME-TIFF) are presented as a single colour image.

• You can select falsecolour and log-scale filters, useful for many scientific images. Scale and offset sliders let you adjust image brightness to see into darker areas (useful for HDR and many scientific images).

• Select Save as to write an image. It can write most common formats, and lets you set file save options. It can write things like DeepZoom pyramids, PFM, OpenEXR, and so on.

• Select Properties (alt-Enter) to see image metadata. It can display large amounts of metadata (useful for eg. DICOM) with filtering.

• Use alt-Left and alt-Right to move between the set of images being displayed, handy for browsing a directory of images. If you drag or load a set of images, it'll flip between the images in the set. If you drag or load a single image, it'll flip between all the images in that directory.

• It keeps the most recent three views live, so you can flip between them very quickly, and all view settings are preserved. This is handy for comparing details on two images.

• Duplicate window crtl-D makes a copy of the window, so you can compare two images side by side.

• It supports copy/paste and drag/drop of filenames, sets of filenames, and textures. You can paste from the screenshot tool, or drag-drop images from your file browser, for example.

• It uses the gtk4 GUI toolkit, so the interface is fast, attractive and nicely animated. The image is rendered with the GPU, so display ought to be quick.

Shortcuts

• Cursor keys to scroll around
• Cursor keys plus shift to move by a screen size
• Cursor keys plus ctrl to move to image edges
• Number keys to pick a particular magnification
• Ctrl + number keys to pick a particular zoom out
• 0 for best fit
• d, to toggle debug rendering mode
• i, + / o, - to zoom in and out
• ctrl-< / ctrl->. prev page, next page
• alt-Left / alt-Right. prev image, next image
• Mouse drag to pan
• Mousewheel to zoom
• Mousewheel + shift/ctrl to pan
• ^O replace image
• ^S save image
• ^N new viewer
• ^D duplicate view
• alt-Enter toggle properties
• ^C / ^V copy paste of filenames, lists of filenames and textures
• F11 fullscreen

Additionally, you can drag and drop filenames, lists of filenames and textures.

Build from source

cd vipsdisp
meson setup build --prefix=~/vips
cd build
ninja
ninja install

And to run:

export GSETTINGS_SCHEMA_DIR=/home/john/vips/share/glib-2.0/schemas
vipsdisp ~/pics/k2.jpg

Version bump checklist

Version needs updating in the following places:

• CHANGELOG.md

• meson.build

• org.libvips.vipsdisp.metainfo.xml and some release notes and a date as well. Be exttremely careful with date formatting, and include leading zeros on the day and month.

• org.libvips.vipsdisp.json needs the version number as a git tag.

flatpak

Add the flathub repo:

flatpak remote-add --if-not-exists \
  flathub https://flathub.org/repo/flathub.flatpakrepo

Install the gtk4 SDK and runtime:

flatpak install org.gnome.Sdk//45
flatpak install org.gnome.Platform//45

Allow file. Recent security changes to git will cause submodule checkout to fail inside flatpak. If you get errors like fatal: transport 'file' not allowed, re-enable file transport with:

git config --global protocol.file.allow always

Build and try running it:

flatpak-builder --force-clean --user --install build-dir org.libvips.vipsdisp.json
flatpak run org.libvips.vipsdisp ~/pics/k2.jpg

Force a complete redownload and rebuild (should only rarely be necessary) with:

rm -rf .flatpak-builder

Check the files that are in the flatpak you built with:

ls build-dir/files

Uninstall with:

flatpak uninstall vipsdisp

Notes on flatpak build process

• niftiio is annoying to build, skip it.

• x265 is annoying to build, skip it

• we skip imagemagick as well, too huge

Packaging for flathub

Install the appdata checker:

flatpak install flathub org.freedesktop.appstream-glib
flatpak run org.freedesktop.appstream-glib validate org.libvips.vipsdisp.metainfo.xml

Also:

desktop-file-validate org.libvips.vipsdisp.desktop 

Uploading to flathub

Make a PR on:

    https://github.com/flathub/org.libvips.vipsdisp 

then check the build status here:

    https://flathub.org/builds/#/apps/org.libvips.vipsdisp

On success, merge to master.

TODO

• skip unknown files on next / prev?

  • need to add the test to next-image, not glob, since we can't test the whole dir on startup

  • need to use next-image to pick the start image (not always the first)

  • need to not do this if only one file specified, eg. vipsdisp x.txt

• PDF page change does not change image size if pages vary in size

• ^C during a slow load leaves a file in /tmp, can we improve this?

• batch save?

• pass revalidate down to new_from_file on F5

• have a look at the new 4.14 gtk_print_dialog_new()

  works and is in branch add-print-dialog, but it needs 4.14, and the new print API is still unstable

• allow eg. "vipsdisp x.svg[scale=10]", the load dialog should have a "load options" expander

• can we move new_from_file into a bg thread? the GUI will pause on huge SVGs on zoom change right now

  very difficult with the current structure -- we'd need to separate tilesource and tilecache completely, and perhaps link them with signals

• tile read errors:

  $ ./src/vipsdisp ~/pics/ome/LuCa-7color_Scan1.ome.tiff

    - (vipsdisp:110067): VIPS-WARNING **: 18:05:16.244: 
        error in tile 0 x 256: tiff2vips: 
            out of order read -- at line 3328, but line 256 requested
  

  page 0, subifd 2 and subifd 3 are untiled!!!

  we need to decompress the whole layer before we view :(

• need to separate page and zoom for ome-tiff, since we have many-page subifd pyramids

  • useful for fixing PDF zoom in the way we fixed SVG zoom too

• pages as bands

  $ ./src/vipsdisp ~/pics/ome/LuCa-7color_Scan1.ome.tiff

    flip to last page, zoom, lots of repaint errors
  
    maybe join first N pages (while pages same size) in pages as bands 
    mode?
  
    does not page flip to smaller pages correctly
  
        reset zoom/scroll on pageflip if the page size changes?
  
    same for audi r8 pdf page flip I guess?
  

• info bar:

  • pages as bands ... info bar displays only one band

  • will not display complex numbers correctly ... need to unpack to bands, or does getpoint do this already?

• zooming:

  • better pinch zoom support

    we should take the coordinates of the pinch gesture into account

    can test this now I have a multitouch trackpad

  • we could shrink tiles on zoom out (we only expand tiles now)

  • before we can do fancy PDF zooming, we'll need to split page and zoom in tile_source_open()

• how should we handle images which include labels, macros, thumbnails?

  • load options? save options?

  • display images in properties? perhaps a thumbnail? set attach-associated?

    appear as eg.:

    openslide.associated.thumbnail 1024x732 uchar, 4 bands, srgb

vipsdisp's Issues

Tests of vipsdisp WSI viewer with various DICOM WSI from Imaging Data Commons

Hi! I am working on the Imaging Data Commons (IDC) project together with @fedorov and @dclunie. We came across your vipsdisp viewer and tested it with some WSI that we have available. They are all in DICOM format and could be displayed. However, in contrast to many other WSI formats, each DICOM file represents only one level of the WSI pyramid. The Vipsdisp viewer doesn't seem to be able to recognize other matching DICOM files in the same location.
We thought that this could be a valuable improvement.

Best regards,
Daniela

Why dependency on gtk4-wayland instead of gtk4?

vipsdisp/meson.build

Line 41 in 31d2b94

gtk_dep = dependency('gtk4-wayland')

Why dependency set to be on gtk4-wayland? GTK4 can be built without Wayland backend.
I have replaced gtk4-wayland with gtk4 and was able to build vipsdisp successfully and run it under Broadway backend.

Pixelation when zoomed in

How can i see the individual pixels when I zoom in? I always see a smooth image even when I zoom in fully. Is there a change to make in the imagedisplay object or does it have to with gdktexture in the tile object or is it in the settings in libvips? Could you please help with that? Thanks!

avif support

On the lib it says there is AVIF support.
On the readme of this it does not say that.

Is it supposed to have it or missing something?

My install method is flatpak if it matters, seems you're maybe involved there too
https://github.com/flathub/org.libvips.vipsdisp
(unless it's automated)

MimeType in desktop file

Could MimeType for the supported formats be added to the desktop file so it can be easily integrated into the desktop environment?

https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s10.html
https://specifications.freedesktop.org/desktop-entry-spec/latest/apa.html

Flatpak?

This will be very promising (I love libvips!) to be used as a replacement for Eye of GNOME and gThumb (not available as flatpak).

macOS build

Shouldn't be too hard, see:

https://wiki.gnome.org/Projects/GTK/OSX

The old gtk2 build system for nip2 is here:

https://github.com/jcupitt/build-osx

vipsdisp is stuck with one theme

I installed this application with flatpak. If a theme is installed with flatpak and that theme is downloaded and applied via dconf, this application currently does not apply the currently used theme. Other applications change theme, but this one sticks with the old-ish Adwaita look. A current workaround is to change flatpak filesystem permissions to allow xdg-data/themes and then use GTK_THEME debug variable to forcefully apply a theme.

How we can use vipsdisp with pyvips to see live stitching process.

I am working on stitching part. but now i am able to see the result after the stitching part complete. so i want to see live process of stitching tile by tile.

Add license

Hi @jcupitt et al,

that's a fantastic tool, thanks for sharing! I was just wondering under which conditions one could reuse the tools and code provided here. Would you mind adding a license file? If you're new to licensing and/or wonder which license to use, you can read more in this blob post: https://focalplane.biologists.com/2023/05/06/if-you-license-it-itll-be-harder-to-steal-it-why-we-should-license-our-work/

Thanks!

Best,
Robert

Feature request: Pinch-to-zoom instead of scroll-to-zoom

Collaborating on this project

Hi! I just discovered the existence of this VIPS-based image viewer, and I am very much interested in helping you to extend the functionalities of vipsdisp.

At the moment I have just forked the project and added some travis ci configuration that allows to automatically build and generate an AppImage package for the application.

However, I have few suggestions on which I am ready to contribute:

1. add proper color management that takes into account the monitor profile (if I understand correctly, at the moment the image is converted to sRGB)
2. improve zooming speed by pre-computing a bunch of scaled-down copies
3. change the "best fit" zoom mode so that it shows the full image, and center it in the preview area
4. full screen and slideshow modes (but at a second stage)

The idea would be to take advantage of VIPS resizing speed and multi-threading to create a fast and lightweight image viewer with accurate color management, something that seems to be in quite some high demand in the FLOSS community.

What do you think?

Build VIPSDISP on windows

Hi @jcupitt, is there any way I can build vipsdip on Windows? I successfully built it from source on ubuntu, and I tried to install everything I needed on MINGW64. The problem I faced is in meson.build find_library 'm', so I bypass it using cc.find_library('m', required: false). But when I try to run ninja I got a lot of errors.
here a copy of part of errors:
FAILED: src/vipsdisp.exe.p/meson-generated_.._vipsdispmarshal.c.obj "cl" "-Isrc/vipsdisp.exe.p" "-Isrc" "-I../src" "-IC:/msys64/mingw64/include/libgsf-1" "-IC:/msys64/m ingw64/include/libxml2" "-IC:/msys64/mingw64/include/" "-IC:/msys64/mingw64/include/pango-1.0" "-IC: /msys64/mingw64/include/harfbuzz" "-IC:/msys64/mingw64/include/fribidi" "-IC:/msys64/mingw64/include /librsvg-2.0" "-IC:/msys64/mingw64/include/gdk-pixbuf-2.0" "-IC:/msys64/mingw64/include/webp" "-IC:/ msys64/mingw64/include/cairo" "-IC:/msys64/mingw64/include/freetype2" "-IC:/msys64/mingw64/include/l ibpng16" "-IC:/msys64/mingw64/include/pixman-1" "-IC:/msys64/mingw64/include/OpenEXR" "-IC:/msys64/m ingw64/include/Imath" "-IC:/msys64/mingw64/include/openjpeg-2.5" "-IC:/msys64/mingw64/include/orc-0. 4" "-IC:/msys64/mingw64/include/glib-2.0" "-IC:/msys64/mingw64/lib/glib-2.0/include" "-IC:/msys64/mi ngw64/include/gtk-4.0" "-IC:/msys64/mingw64/include/graphene-1.0" "-IC:/msys64/mingw64/lib/graphene- 1.0/include" "-I." "/MDd" "/nologo" "/showIncludes" "/utf-8" "/W2" "/std:c11" "/Od" "/Zi" "-DHAVE_CO NFIG_H" "-mfpmath=sse" "-msse" "-msse2" "-DLIBDEFLATE_DLL" "/Fdsrc/vipsdisp.exe.p/meson-generated_.. _vipsdispmarshal.c.pdb" /Fosrc/vipsdisp.exe.p/meson-generated_.._vipsdispmarshal.c.obj "/c" src/vips dispmarshal.c CreateProcess failed: The system cannot find the file specified.

Any suggestions?

JPEG XL Support: Does not support container format.

This viewer does not open JXL files that have a container, instead returning the error VipsForeignLoad: source is not a known format.

It does work for images with the container removed, or which where created without the container (which is the default for encoding jxl images from pixels.)

Here is a working example: (Remove .txt extension, its only there to allow GitHub upload)
no-container.jxl.txt
Here is a non-working example:
container.jxl.txt

Image Viewer using pyvips?

How would you recommend using pyvips to perform visualization instead of using the C version of vips? I am asking this because I couldn't find the vips_sink_screen function implemented in any of the Classes in pyvips.

Also, if I want to build a visualizer using libvips, is the C implementation my only option?

Support HiDPI displays

When using a HiDPI display (2x scale), the base image which is being viewed is a (much) lower resolution than desired.

So, the low resolution image is scaled up and it looks ugly.

(don't mind my semi-transparent windows and lack of checkerboard background: I like to theme [your] app)

I'm not sure where to start, but (after some direction), I'd love to work on this (and the SVG DPI upscaling as well).

Add multiple file support

RFE - Are you able to please add keyboard shortcuts for moving forward/backwards through multiple image files in a directory. Currently if there are multiple images in the same directory, from Nautilus file browser I open the first image file for viewing. Then to view the second image, I need to use the 'Replace Image...' dialog or go back to Nautilus and double-click on the next file. This is slow for moving through dozens or hundreds of image files in a directory. Perhaps as mentioned in the vipsdisp TODO list, something like Shift-left and Shift-right? Similar to Gnome Image Viewer (EOG) using left/right arrow keys to move through multiple image files.

Fedora 38, vipsdisp 2.6.3 as a flatpak from flathub.org

VipsDisp 2.5.1 compiles on Windows, but does not run with VIPS 8.15.0 rc1 release

I compiled VipsDisp 2.5.1 latest source release on Windows with new version of libvips (vips-dev-8.15.0 rc1).
Previous version (8.14) cannot be used, because vips_thread_execute was added to API in 8.15.
However, the executable does not run and gives an error "Procedure entry point g_regex_new could not be located in the dynamic link library libglib-2.0-0.dll"
Dependency Walker shows that the entry point of g_regex_new in libglib-2.0-0.dll, supplied with 8.15 rc1 binary package, does not exist.
So, it seems that this dll in 8.15.0 rc1 release is outdated.
Where could I find libglib-2.0-0.dll with g_regex_new function defined?

2 issues and 1 suggestion with latest version 3.0.4 on windows

Vipsdisp version : 3.0.4
Windows 10, 64bit

1- in touch screen, pinch and zoom with fingers is not working. move the image with 1 finger is working. It was working on the previous version 2.6

2- go to Next/Previous image is only working on the to menu bar (close to Open), it does not work on the menu (or right click menu). This is a problem for Full screen mode.

3- Suggestion: Add a Sync option if we are opening multiple similar images and we zoom on first image and we go to next image, if the "Sync" option is selected, the second image will be zoomed to the same location. The coordinates (X and Y) and zoom level will be preserved from image to image.

How to use vipsdisp for pyvips python

Hello @jcupitt,
I am using pyvips for my project and it's helping me lot in mosaicing image. Thanks for such a wonderful tool. :)
Now I want to display my final image using vipsdisp. I am figuring out how i can use this with my pyvips code. I haven't found any documentation to integrate it with pyvips, can you suggest how to integrate this.

This code is just for reference:

import os 
from os.path import isfile, join
import re
import sys
import pyvips
import numpy as np
from tqdm import tqdm

images = []
mypath="/media/lab/Seagate Backup Plus Drive/Hinduja Scans/CASE6/CASE6_2_focused/"
onlyfiles = [ f for f in os.listdir(mypath) if isfile(join(mypath,f)) ]
images = np.empty(len(onlyfiles), dtype=object)
onlyfiles.sort(key=lambda var:[int(x) if x.isdigit() else x for x in re.findall(r'[^0-9]|[0-9]+', var)])

row=10
column=50
x_overlap=480-92
y_overlap=640-164
blend_size=100
n=0
y=0

for r in tqdm(range(row)):
    x=0
    
    for c in range(column-1):
        x+=x_overlap
        if c==0:
            tile1 = pyvips.Image.new_from_file(join(mypath,onlyfiles[n]), access="sequential")
        tile2 = pyvips.Image.new_from_file(join(mypath,onlyfiles[n+1]), access="sequential")                                            
        tile1 = tile2.merge(tile1, 'horizontal', -x, 0, mblend =blend_size)    
        n+=1
    if r==0:
        column_stitch=tile1
    if r>0:
        column_stitch = tile1.merge(column_stitch, 'vertical', 0, -y, mblend =False)    
    y+=y_overlap        
column_stitch.write_to_file('test.tiff',bigtiff=True)

To run this set :

• mypath
• row
• column
• x_overlap
• y_overlap

I want to dispaly column_stitch, final mosaiced image using vipsdisp.

Add copy/paste and drag/drop support

Two obvious missing features. We'd need to support filename and image drag-drop/copy-paste.

https://docs.gtk.org/gdk4/class.Clipboard.html

https://docs.gtk.org/gtk4/drag-and-drop.html

Compile error in Centos 8

gcc  -g -O2   -o vd disp-gresources.o settings.o disp.o gtkutil.o tslider.o infobar.o imageview.o imagepresent.o conversion.o conversionview.o imagedisplay.o -I/usr/include/gtk-3.0 -I/usr/include/pango-1.0 -I/usr/include/glib-2.0 -I/usr/lib64/glib-2.0/include -I/usr/include/fribidi -I/usr/include/cairo -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng16 -I/usr/include/uuid -I/usr/include/harfbuzz -I/usr/include/gdk-pixbuf-2.0 -I/usr/include/gio-unix-2.0/ -I/usr/include/atk-1.0 -I/usr/include/at-spi2-atk/2.0 -I/usr/include/at-spi-2.0 -I/usr/include/dbus-1.0 -I/usr/lib64/dbus-1.0/include -pthread -I/usr/include/orc-0.4  -lgtk-3 -lgdk-3 -lpangocairo-1.0 -lpango-1.0 -latk-1.0 -lcairo-gobject -lcairo -lgdk_pixbuf-2.0 -lgio-2.0 -lvips -lgobject-2.0 -lglib-2.0  -lm 
conversion.o: In function `conversion_set_source':
/vips_imageviewer/vipsdisp/conversion.c:371: undefined reference to `vips_image_get_n_subifds'
conversion.o: In function `conversion_set_file':
/vips_imageviewer/vipsdisp/conversion.c:550: undefined reference to `vips_source_g_input_stream_new'
collect2: error: ld returned 1 exit status
make: *** [Makefile:396: vd] Error 1

The autogen.sh was run and got this error, I am having vips version vips-8.11.0-Tue Apr 27 16:00:48 UTC 2021
which package I might have missed.