Pix Documentation

Introduction

Pix is a viewer for JPEG, GIF, PNG, and HEIC pictures, as well as MPEG videos and QuickTime movies. I wrote it (2004 in Java, 2014 in Objective-C, since 2015 partly, since 2017 almost entirely, since 2019 entirely in Swift), because I needed functionality I could not find in the existing JPEG viewers for Mac OS X (e.g. the ability to recognize all JFIF files irrespective of their name, the search for similarly looking pictures, or the ability to walk backwards in a randomly ordered slide show). It is inspired by the excellent Macintosh programs "JPEGView 3.3.1" by Aaron Giles and "Show! 1.0.3" by Henk W den Bok, both of the year 1995.

Installation

The only known way of obtaining Pix is to download it from here. (Decompress it using a ZIP utility like the "Archive Utility" of Mac OS X or the "StuffIt Expander".)

By default, Pix tries to check on start-up whether a newer version is available at https://www.jakob-spies.de/pix/. If so, it will ask you whether you want an automatic update. If so, Pix starts a helper application, PixUpdater, which downloads https://www.jakob-spies.de/pix/Pix.zip (note that this is a TLS connection where the web server's identity is verified), decompresses it, verifies the code signature, quits the running old Pix, and replaces it with the downloaded one.

The automatic version check can be switched off in the Preferences dialog.

Video Support

Pix can open and display video files the lower-cased name of which usually ends with ".mp4",".mov", ".mpg", ".m4v", ".m1v", ".mpeg", ".vob", ".avi", ".ts". Other file types it can try to let macOS open when they occur in a slide show.

There is a special handling of files the lower-cased name of which ends with ".m3u8". These are treated as index files of M3U8 MPEG streams. If you try to open one with Pix, then Pix will function as an HTTP server, listening on port 3005, and tell Safari to open the local HTTP URL corresponding to the file. So if you have downloaded an M3U8 stream, e.g. using Filmbeschaffer, you can use Pix for viewing it, without having to start an extra HTTP server.

Example: You have downloaded an M3U8 stream into folder /Users/jakob/nice film, which then contains index.m3u8 and some files the name of which ends in ".ts". Opening index.m3u8 with Pix causes Safari to open http://localhost:3005/Users/jakob/nice%20film, which will then make the video play in Safari.

The HTTP server will allow only connections from localhost, so don't be afraid that it exposes your file system to the Internet.

Usage

Features and properties not explained in this documentation are regarded as obvious or irrelevant.

"open with Pix"

The script open with Pix.workflow contained in the distribution has the following purpose. If you put it into the folder /Library/Services or ~/Library/Services, you can assign a keyboard shortcut to it, using the "Shortcuts" tab in the "Keyboard" section of the System Preferences. And then, if you press the configured key combination, Pix will open windows for the items selected in the finder: a thumbnails window for the selected folders and picture windows for the selected image or video files.

Menu "File"

The submenu Open Recent serves only for rerunning recent slide shows.

The command Close Single Pictures closes all windows except for slide show and thumbnail windows.

The command Close All closes all windows except slide show windows.

The Thumbnails… menu command lets you choose folders for the Thumbnails View, using the macOS dialog.

Menu "Edit"

The command Append Row appends a row to a table, like the "Search Exclusions" in Pix's preferences.

Menu "Media"

Mute Video Clips

… mutes/unmutes all video player views. This setting is not persisted; Pix always starts in muted mode.

Search Similar…

… searches the configured search folder for images that have a "similarity distance" less or equal to the value configured as "Max. Distance" in the "Fingerprints" preferences from the currently opened image (in case of animated GIF images the first frame is taken for the comparison). See Fingerprints Database for more information about this feature.

Open Database…

… opens the fingerprints database window, cf. Fingerprints Database.

Find Neighbors…

This menu item is for seeking pairs of images with low fingerprint distance. If executed on a large set of images, this can be a lengthy procedure. Therefore the menu item opens a little window showing the current search state. If a search is running, it can be stopped using the "Stop" button. Otherwise it can be started with the "Start" button. The search produces a file neighbors n at the root of the configured root folder, where n is the maximal distance entered in the "Find Neighbors" window, and for each pair of images the fingerprints have a distance of at most n the file contains the relative path of one of these images.

if n = 0, then the search is quick, with linear complexity (i.e. execution time proportional to the number of images). For n > 0 the search has quadratic complexity. Pix does by far not compute the distance between each pair of fingerprints, but despite all optimizations of the algorithm it has quadratic complexity. The consequence is that the search (with low values of n) is fairly quick for, say, 10,000 images, it takes an acceptable amount of time for 100,000 images, but forget about running it over 1,000,000 images.

In the preferences of Pix, under "Search Exclusions", you can maintain a set of character strings which have the following meaning: If the relative path of a media file (with respect to the configured root folder) contains one of these strings, then it is excluded from the neighbors search. The button "Clean" removes all strings that do not actually exclude any existing path from the list.

Menu "Folder"

By Name…

This menu command lets you choose folders inside the configured root folder for the Fingerprints Database by their (case-insensitive!) names, which can be much faster than navigation in Finder or a regular dialog for choosing a folder — if you have a complex folder structure. The implementation is optimized for the search for folders the name of which starts with the input string (because this is assumed to be the default use case); the search for folders the name of which only contains the given string is slower. Invisible characters in folder names can cause unexpected search results. The selected folders can be openend or used for the thumbnails view by double-clicking the desired row or selecting rows and then pressing the "Open" resp. "Thumbnails" button. Opening resp. thumbnails creation can also be achieved using the keyboard shortcuts cmd-O resp. cmd-T.

Pix keeps the folders databaase in memory and does not update it after it was created. For adapting it to changes in the file system you have to restart Pix.

Find First…

This menu item does the following: Pix will ask you for a folder. Then it will determine the smallest positive natural number such that this folder does not contain a subfolder the name of which starts with this number, and will create a subfolder having this number as its name.

Find Superfluous…

This menu item does the following: Pix will ask you for a folder ƒ. Then it will list in a new window under the heading "Quasi-Empty Folders" all folders inside ƒ that contain only irrelevant files like ".DS_Store" or "Icon\r", where '\r' is the carriage return character. Clicking on an item in the list opens the respective folder in the Finder. All these folders can be moved to a common location using the button "Move All Quasi-Empty…". The button "Cancel" cancels parsing ƒ.

Creation Date Statistics…

This menu item does the following: Pix will ask you for a folder. Then it will generate the curve of a monotonously increasing function from time to numbers. The curve indicates how many files in the chosen folder have a creation date before a certain point in time. Creation dates before 1991, which are most probably wrong, are treated like the earliest date of a file not falling into this category. You can zoom in and out by clicking into the view while the + resp. - key is pressed.

Synchronize Tags…

This menu command synchronizes the tags between two folders. You choose a source folder and a target folder, then Pix iterates over the files in the source folder (including nested folders), and if it finds a file in the target folder that has the same relative path as the file in the source folder, it changes, if necessary, the target file such that both are either marked or not.

Encipher Folder…

This menu item enciphers the contents of a folder. You choose a source folder and a target folder, and then Pix enciphers the contents of the source folder into the target folder, keeping the folder structure and file names. The cipher used for this is AES with a key of 256 bits. The cryptographic key is stored in your key chain. Using this key, Pix is able to decipher on-the-fly and display images enciphered in this way. This provides for viewing pictures while they are persisted only in enciphered form.

Decipher Folder…

This menu item performs just the inverse operation: Decipher the contents of a folder into another folder, using the key previously stored in the user key chain.

Pick Folder

This menu item tells Pix to remember the current folder, which causes this folder to be preselected in the next (and only the next) dialog where a folder is chosen.

Move Folder

This menu item tells Pix to move the current folder (i.e. the root folder of a thumbnails window or the parent folder of the currently selected or displayed media item) to a location you can choose. This can also be used to rename folders.

Update Folder Database

This menu item tells Pix to adapt its internal folder database to the real contents of the root folder.

Menu "Window"

The menu items corresponding to slide show windows are marked with a leading "runner" symbol".

The Views of Pix

Release Notes

New in Version 7.1.1

New in Version 7.1

New in Version 7

New in Version 6

The similarity search.

Known Limitations

Known Bugs

The thumbnails view has a memory leak. This looks like a bug in Apple's NSCollectionView.

Photos can contain hints how they have to be rotated to be displayed in the correct orientation. Usually this works fine with Pix, but in rare cases not. The cause is again in macOS, because the responsible system function does not rotate the image. Pix knows that the image has to be rotated and could easily do so, but this does not help, because it has no way of knowing whether the image given to it by the system has already been rotated (like in most cases) or not.

Certain old JFIF images cannot be read under Mac OS X 10.10 and higher, while previous Mac OS X versions were able to handle them. This is a bug in Mac OS X resp. macOS ≥ 10.10, reported to Apple under number 18893712. As a workaround such images can be saved with GraphicConverter ("lossless cropping").