Basic guide to the User Interface
The user interface is always topped by five tabs, which are
These control the overall mode of the program. You can switch between them at any time without losing work.
At the bottom, in all modes, is the Queue. The queue provides a place for images you want to work on.
Most buttons and tools will have thorough tooltips giving you useful information when you hover over the names; if you forget something these provide a quick reference.
The Import tab has a list of sliders and text entry boxes on the left, and some preset buttons on the right.
If any of the presets fits your use case, press the corresponding button and it will set up Filmulator to import in the way that you need.
Most of these settings are remembered so that when you close the program and reopen it, you'll be in the same place. One exception is the source directory or file, which you have to choose each time, and the two sets of radio buttons which default to importing from a directory and importing in place.
Usually you can close the program at any time without problems. If you're currently importing, nothing bad will happen but you will have to start the import over. Anything that was already imported will be skipped over rapidly.
- The Camera UTC Offset slider tells the program what time zone the camera is set to. This is remembered across editing sessions so you don't have to change it unless you actually change it on your camera(s).
- The Import Directory/Import Files radio button set lets you choose to import either all the raw files contained within a directory, or just one (or multiple) files.
- The Source Directory text entry box, visible when Import Directory is selected, lets you choose a directory to import from. Either type it in, or click on the Select a Directory button to use a graphical dialog box. It will recursively search all subdirectories for raw photos. If you see a warning triangle, hover over the text box and a tooltip will explain what needs to be done to remedy the issue.
- The Source Files text entry box, visible when Import Files is selected, lets you choose one or more files to import from. You can enter a comma-separated list of absolute file paths, or you can just click on the Select Files button to use a graphical dialog box. If you see a warning triangle, hover over the text box and a tooltip will explain what needs to be done to remedy the issue.
- The Copy to directory/Import in place radio button set lets you choose to either copy all the files into an organized file structure, or to simply leave them where they are. When choosing to import in place, any irrelevant settings are hidden.
- The Local UTC Offset slider, visible when Copy to directory is selected, tells the program what time zone the photos were taken in. This does not refer to the time zone setting of the computer you're using. This only affects what year/month/day filesystem folders the images are sorted into, in case you ever are accessing the photos using a normal file browser outside of Filmulator.
- The Destination Directory text entry box, visible when Copy to directory is selected, sets the folder that imported photos will go in. For example, you may want to set it to your Photos directory, or a subfolder of that if you want to have the root of your Photos directory clean. If the root directory doesn't exist (say if you typed it in), it will be created. If you see a warning triangle, hover over the text box and a tooltip will explain what needs to be done to remedy the issue.
- The optional Backup Directory text entry box, visible when Copy to directory is selected, sets an optional destination for a simultaneous backup of your raw files when you import. If this does not exist, (for example, if it's an external hard disk that's not connected) it will not be created and the files will not be backed up.
- The Directory Structure text entry box, visible when Copy to directory is selected, sets the directory structure of the files. This has considerable flexibility. You can use date and time string descriptors (as shown in the below table) as long as they're separated by punctuation, and you can also use words and phrases in 'single quotes'. If you expect to be importing large numbers of files into relatively few directories, such as an entire vacation's worth into one dedicated folder, it's suggested to enable the Append unique identifier option.
| Expression | Output |
|---|---|
| d | the day as a number without a leading zero (1 to 31) |
| dd | the day as a number with a leading zero (01 to 31) |
| ddd | the abbreviated localized day name ('Mon' to 'Sun') |
| dddd | the long localized day name ('Monday' to 'Sunday') |
| M | the month as a number without a leading zero (1 to 12) |
| MM | the month as a number with a leading zero (01 to 12) |
| MMM | the abbreviated localized month name ('Jan' to 'Dec') |
| MMMM | the long localized month name ('January to 'December') |
| yy | the year as a two-digit number (00 to 99) |
| yyyy | the year as a four digit number |
| h | the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display) |
| hh | the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display) |
| H | the hour without a leading zero (0 to 23, even if AM/PM display) |
| HH | the hour with a leading zero (00 to 23, even if AM/PM display) |
| m | the minute without a leading zero (0 to 59) |
| mm | the minute with a leading zero (00 to 59) |
| s | the second without a leading zero (0 to 59) |
| ss | the second with a leading zero (00 to 59) |
| AP or A | use AM/PM display. AP or A will be replaced by either 'AM' or 'PM'. |
| ap or a | use am/pm display. ap or a will be replaced by either 'am' or 'pm'. |
- The Append unique identifier switch, visible when Copy to directory is selected, lets you choose whether or not to append a hash of the raw file to the end of the filename. This is useful when shooting many pictures a day with multiple cameras of the same brand; otherwise you may get filename conflicts.
- The Update file locations switch, visible when Import in place is selected, will go through the selected files and update their locations as recorded in the database, if they already exist. This is useful for managing backups: periodically use
rsyncto copy your main photo directory (and exported images!) to an external hard disk, and then import-in-place with updated file locations. After you do this, you can delete the photos from your main processing directory. Simply reconnect your external if you want to have access to the photos in Filmulator. - The Enqueue imported photos switch lets you choose whether or not to enqueue each photo as it is imported, or to wait until later to enqueue them. If you only want to process a few out of a big import batch, turn this switch off. When updating file locations en masse (see previous bullet), it's suggested that you turn this off.
- Import. Press this button to begin importing. Pressing it a second time does little harm; it'll rapidly scan through the same source directory a second time but it won't actually process the photos a second time.
- The progress bar. Hover your mouse over it for a numerical version of its progress.
The mechanics of importing are described here:
- If a file of the same name exists in the same location on the backup already, the new one will not overwrite it.
- IF there is no file of the same name in the same location on the backup, the file will be copied over.
- If the file has an exact match in the database, the new version will be copied to the main destination whether or not it is there.
- If the file does not have an exact match in the database, it will be processed to generate a thumbnail, copied to the destination directory, and entered into the database.
If updating the file locations:
- If a file shares the same contents as one that already exists in the database, the database will change that photo's entry to point at the newly imported file.
- If the file does not have the same contents as one that already exists in the database, it will be ignored.
The organize tab features a panel on the left for filtering and organizing, a histogram on the top showing how many photos you took on each day, and a view showing you the images you've filtered down to.
The time zone slider controls when midnight is for dividing the photos between different days.
These sliders let you hide any images with a rating below and above the selected values.
This button lets you instantly place all images currently in the date range that meet the rating criteria in the queue.
Each day gets its own bar. The height of the bar is proportional to the logarithm of the number of images taken that day. It's only going to go off the top if you import every frame of a whole day of extremely high speed footage, and realistically import rate is the limitation there.
Drag leftwards and rightwards to scroll, hover to see what the exact date is, and double-click to select a particular day. If you wish to view photos from a range of dates, double-click on one end of the desired range, and then either right-click or shift-click on the other end of the range. This will show images from all of the days selected. If you right-click or shift-click again, it will select a new range based on the last date you double-clicked on.
You can also navigate the date histogram using the arrow keys. When on the Organize tab, the left and right arrows will switch the selected day, and holding shift while doing that will let you select a range of dates.
If you wish to cancel the date range selection, either double-click on a new date or select a day from the calendar in the left panel.
This shows the images on the current day that meet the current ratings requirements.
Hover over a photo to see its filename and capture date. Click on it to select it, which enables you to edit its rating by clicking near the top edge. (More features to come.) Click once more (not on any of the controls) to deselect the image.
Double-click a photo to enqueue it.
Photos that have had settings changed from their initial ones will have a dark green background instead of gray.
Now is a good time to discuss the queue.
The queue is on the bottom of the screen in all modes. You can drag it to change its size from very small to very large; the images scale to fit.
The contents of the queue, like most of the sliders, remain if you close the program and reopen it. One exception is that while Filmulator is in alpha, there may be database changes large enough to warrant completely clearing the queue upon first launch after an update.
Photos are shown side-by-side in the queue. The most recently enqueued photos are added to the right side. You can either drag the images left and right to scroll, or you can use a mouse wheel (or two-fingered scrolling). Below each photo is a status bar. If the bar is orange, the photo has been edited. If it's blank, it's never had a setting changed from default. If the bar is green, the photo has been written to either a JPEG or a TIFF. If only the center third of the bar is green, then the photo has been selected for export but is not saved yet (not implemented yet).
To activate an image to operate on, double-click on it. This is not kept across sessions; if you restart the program you have to find the image you were working on. The selected image will have an orange bar across the top of its queue entry.
You can right-click on a photo to access several operations in a context menu.
- Forget photos will cause Filmulator to forget about all photos that are marked with an X and are currently in the queue. This will not delete any files, but it will forget the processing parameters used for those files.
- Clear entire queue removes every image from the queue. To prevent accidental activation, it has a timed lockout. To operate it, press the button once, then wait 3 seconds, until "...Wait a moment..." disappears, then click the button while it says "Are you sure?". If you click early while the button reads "...Wait a moment...", it reverts back to the locked initial state. Likewise, if you wait too long after the "Are you sure?" text appears, it will also revert back to the initial state.
- Remove from queue simply removes that one photo from the queue.
- Copy all settings allows you to copy all of the processing settings from the selected image. Partial copy is not yet implemented...
- Paste settings, by default disabled, allows you to paste all of the copied settings onto a selected image. You can do this several times without needing to copy multiple times, but after switching which photo is active or moving a slider in the Filmulate tab, it will 'forget' and you will have to copy again.
- The bottom row of buttons X and 0 through 5 allows you to give the selected photo a rating (which carries over to the Organize tab). The current rating is grayed out. If you set the rating to X, that makes the image eligible for forgetting as long as it remains in the queue.
When on the Filmulate tab, you can switch between active images by pressing right or left. You can also adjust the rating of the current image by pressing up or down, or alternately by pressing X or 0 through 5 to directly set the rating.
The Filmulate tab is where you actually perform edits on photos. This will just give a brief overview of the interface; another article describes how best to process photos.
The right side features a panel with a histogram and the controls for various processing parameters. On the top is a histogram of the brightness values for the current image. Below that is a list of processing tools, with a pair of small histograms giving you brightness information at various stages in the processing pipeline. The tools and small histograms are precisely in the order in which they are applied to the photo from top to bottom.
At the bottom are the buttons "Save TIFF" and "Save JPEG". These will save a 16-bit uncompressed TIFF and 8-bit JPEG, respectively, to the same directory the raw file is in. It will be named [image-name]-output.[extension].
Most of the tools are operated by sliders. Either you can click the gray handle and drag to adjust the value, or you can simply left-click on the orange bar and the handle will jump to the mouse location.
To reset the slider to its default value, you can either double-right-click anywhere on the slider handle or bar, or you can click the [] button.
If the orange slider bar has black dots in it, then it will snap to those discrete values.
Any other slider may be continuously adjusted. If you wish for additional precision in adjustment, right-click on the tool name to reveal or hide a circular dial. Drag anywhere beginning in the circle (including the small inner circle) to adjust the slider. Clockwise dragging will move the slider to the right, while counterclockwise dragging will move the slider to the left. Eight full revolutions of the circle is equivalent to the full range of slider motion. You may drag with the mouse cursor out of the circle; this can result in extreme precision of adjustments.
In top of the main part of the window is, from left to right, a progress bar for the current processing, some information about the currently active photo, then buttons for changing the background brightness, white balance sampling, cropping, and image rotation and leveling.
In the main part of the window is the image display viewport. The image is always shown scaled from the full resolution, allowing you to zoom and pan freely without waiting, and providing an accurate view of how noisy the image is. When you change a processing parameter, by default, it quickly renders a lower resolution preview for greater responsiveness before working on the full image.
When an image is first selected, a thumbnail view is provided for immediate feedback. Once the image is processed, it will then be shown at full resolution.
To navigate, click and drag the mouse. The image has some 'momentum' so even after flicking, it will glide gently to a stop. If you want to stop it sooner, simply click again to 'grab' it and release without moving the mouse.
Zooming can be performed two ways: by double clicking and by scrolling. Scrolling will freely zoom the image about the mouse cursor; you can zoom in until all you can see is one pixel, and you can zoom out until the entire image is smaller than one pixel. A double click will snap the magnification to either fit-to-screen or 1:1, useful if you've zoomed in or out too far.
- Scrolling in always zooms around the mouse cursor. If you zoom in outside of the image, simply drag a bit and it will snap to the nearest edge of the image.
- Scrolling out zooms about the mouse cursor, except if any border is visible after zooming out, it snaps to the nearest edge. If the image is smaller than the viewport, it will recenter the image.
- Double-clicking when the image is smaller than the screen will return the image to fit-to-screen.
- Double-clicking when the image is fit to the screen will zoom to 1:1 about the mouse.
- Double-clicking when the image is bigger than the screen but less than 1:1 will zoom to 1:1 about the mouse.
- Double-clicking when the image is 1:1 will return to fit to screen.
- Double-clicking when the image is bigger than 1:1 will return to 1:1 about the mouse.
- User Interface Scale: how big relative to the default to make the user interface. For a high DPI ('retina') screen, a value from 1.2 to 2.0 is typical, depending on how good your eyes are and how dense exactly the display is. This resizes every aspect of the program except for the 1:1 scale, which remains at 1 image pixel to one device pixel. The reset button on this tool sets it back to the UI scale value from the last time the settings were saved.
- Use system language: turning this switch off will set Filmulator's user interface language to English instead of whatever language your computer is set for.
- Smooth editor image: whether or not to mipmap the editor view when zoomed smaller than 1:1. For noisy images and fine things like wires in the sky, turning this off may result in moire patterns or other artifacts. However, turning this on negatively impacts the sharpness of the view, so you may prefer to leave it off, especially on lower-resolution screens.
- Reduce memory usage: Do not keep intermediate computational results in the full size image. This dramatically reduces responsiveness when not rendering a small preview, but also dramatically reduces steady state memory consumption when working on large images.
- Render small preview first: To make the view respond more quickly to slider motion, render and display a low-resolution preview before proceeding to work on the full resolution preview. This defaults to on; turn this off mainly if you are running out of memory even after turning on Reduce memory usage.
- Preview render resolution: You can select the size of the fast preview you would like. Smaller resolutions will look softer but sliders will respond more quickly and RAM usage will be reduced, while higher resolutions look sharper but reduce responsiveness. The default is 1500 pixels on the long side. The full resolution preview is still computed afterwards regardless of this setting.
Pressing the Save Settings button will record the changes. User Interface Scale, Reduce memory usage, Render small preview first, and Preview render resolution will not change until the program is restarted, but smoothing of the editor image will be applied immediately.
In the second column of the Settings tab you'll find tools that relate to secondary databases of lens and camera info.
The top two are related to Lensfun, the database of lens corrections.
- Check for lens correction updates lets you find out whether there are new lens corrections available.
- Update lens correction database will download the latest database to your computer. Restart Filmulator after doing this to take advantage of the new lens correction info.
The third is for camera constants that for now primarily improve the handling of bright highlights for certain cameras. If you notice purple clipped highlights, try downloading the latest camera constants to correct for it.