Pix Documentation

Introduction

Pix is a viewer for JPEG, GIF, PNG, HEIC, and WebP 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 completely 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.

System Requirements

Operating system macOS 13 or higher.

Installation

The only known way of obtaining Pix is to download it from here.

By default, Pix tries to check on application start whether a newer version is available at https://www.jakob-spies.de/pix/. If so, it will ask you if you want an automatic update. If so, Pix starts a helper application, SoftwareUpdater, 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 Settings 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.

Pressing the button "2" on the keyboard halves the playback rate, allowing for slow motion playback. Hitting "1" resets the playback rate to normal.

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 other files. Opening index.m3u8 with Pix causes Safari to open http://localhost:3005/Users/jakob/nice%20film/index.m3u8, which will then make the video play in Safari.

The HTTP server will allow only connections from localhost, so your file system is not exposed to the network.

Scriptability

The functionality to synchronize file tags is exposed for scripting.

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 media files.

Menu "File"

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

The command Open URL or Path… allows to show in Finder or open files/folders with Pix by entering their URL or path as a character string. The URL can be a file URL, like file:///Users/jakob/funny%20picture, or an HTTP URL pointing to a Pix HTTP server in the local network, like http://host:3005path, where host is the host name or IP address and path the absolute path of the file on this host. The HTTP access will of course only work if the HTTP server of the addressed Pix instance is running.

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

The menu item Run HTTP Server switches Pix's HTTP Server on/off. Security is provided by Pix asking you to allow or deny connections from unknown machines, and these decisions are remembered as long as the Pix process is running.

The commands Import/Export Cryptographic Key… serve for importing/exporting the cryptographic key used for Pix's cipher.

The command Close Non-Slide-Show Windows closes all windows except slide show windows.

Menu "Edit"

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

The commands Undo and Redo work as usual, e.g. for the edition in text fields, but for reverting operations in the file system you have to use the respective items of the Media menu.

Menu "Media"

Thumbnails…

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

Thumbnails

… opens the Thumbnails View for the folder associated to the front window or the items selected in it.

Open Last Restored

… opens the file that was last restored after a deletion (using Undo Last Deletion), provided that only one file was restored.

Seek 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.

Seek Similar to Reverted…

… does the same for the mirrored, i.e. laterally reverted, image.

Open Database…

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

Find Neighbors…

This menu item is for seeking pairs of images with small 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 small 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 having 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. return/enter.

Note that the input gets trimmed, in the sense that whitespace characters are removed from the start and the end. If you write "Sab ", for example, this will be treated as if you had written "Sab".

Pix keeps the folders database in memory and does not update it on its own after it was created. For adapting it to changes in the file system you have to use the command Update Folder Database.

New Folder Search…

Works like By Name…, with the difference that it opens a new search dialog even if there is already an open one.

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 deleted using the button "Delete 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.

In order to let you see whether the synchronization is running or not, Pix displays its application icon in the menu bar while and only while the synchronization is running.

Choose Random File…

You choose a folder and Pix chooses a random file contained in the folder hierarchy rooted in this folder.

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 in Galois Counter Mode with a key of 256 bits. The cryptographic key is stored in your key chain as a password under the name "Pix Key". 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 "Tasks"

A "task" is a pair of two text strings, a "location", which is presumably identifying a location in the file system, and a "comment". Pix keeps a persistent set of such tasks. Tasks can be created with the Create Task… command and can be viewed, processed, and deleted with the Show Tasks command. The command Open Location tells Pix to try to interpret the "locations" of the tasks selected in the tasks view as file system locations and to open them. With Export… you can export the selected tasks to a JSON file, and with Import…, which is only possible if the "Tasks" window is showing, you can add tasks from a JSON file exported from Pix. For deleting tasks just use the backspace or delete key.

Menu "Window"

The menu items corresponding to slide show windows are marked with a leading 🏃‍♀️ symbol if the respective slide show is running, with🧍‍♀️if it is suspended.

The Views of Pix

Release Notes

New in Version 12.9.5

New in Version 12.9

New in Version 12

Known Limitations

Known Bugs