Install and get started

Requirements

Obscura Catalog runs on macOS 12 (Monterey) and later.

Download and install

Obscura Catalog is distributed as a disk image (DMG), signed with Developer ID and notarized by Apple. It is a universal app, for Apple silicon and Intel Macs.

1. Download the disk image of the latest published release from the Obscura member area, profil.obscuraflow.app: sign in, or request an account (see the download page of the Obscura Catalog website).
2. Open the disk image, then drag Obscura Catalog onto the Applications folder. The image also holds the licence (Licence.md) and the list of third-party components (Composants tiers.md, “Third-party components”).
3. Eject the disk image and open Obscura Catalog from the Applications folder.

Updates

Obscura Catalog looks for new releases itself: the Automatically check for updates option is on by default. When a release is published, it offers it in a window that shows its release notes; you choose to install it now, later, or to skip that version. Nothing is installed without your consent. Obscura Catalog › Check for Updates… looks for one on demand (see Settings).

First launch

On first launch, Catalog creates an empty library and opens the Library section, which shows “No files”: “Import a folder: its images stay where they are, Catalog describes them.”, with the Import a folder… button.

The Activate Obscura Catalog window opens too: sign in with the account that holds your licence, or click Continue without a licence (see Licence and free tier).

To begin:

1. Click Import a folder… and choose a folder of images (see Import a folder).
2. Browse the images in the grid, rate them, describe them (see Browse the library).
3. When you are ready to catalogue, open Works and create your first work (see The catalogue raisonné).

The main window

On the left, the sidebar opens with the Obscura Catalog symbol and name, followed by the number of the installed version. It then lists the sections in four groups:

• Library — Library (all files and the imported folders), Collections and search, Faces, Thesaurus;
• Catalogue raisonné — Works, Agents, Exhibitions, Publications;
• Exchanges — Imports (tabs Files, Lightroom, CSV), Exports;
• Attest — Reports, Certificates.

The toolbar, at the top of the window, holds Back and Forward (to return to a record opened from another one, see below), the ? button, which opens the in-app help article on the screen shown, and the licence button (see Account and licence). In Library and Collections and search, a last button shows or hides the inspector.

A folder import keeps running while you move to another section. Each section keeps its state, too: when you come back, the selected work and its record being edited, a CSV or Lightroom import at the step you left it, a report’s options are all there. On the next launch, Catalog reopens the section you were in, with the work, agent, exhibition or publication that was open in it.

Unsaved changes are not lost when you change section: a dot marks them in the sidebar, next to the section, and in the window’s close button. Closing the window or quitting Catalog then asks Save, Don’t Save or Cancel.

Menus and keyboard shortcuts

Every command is in the menu bar, with its shortcut, and stays dimmed while it does not apply (nothing to search in the section, no record to go back to, a folder import already running):

• File — New Work (⌘N, from any section), New Library…, Open Library…, Close (⌘W), Back Up Library, Restore a Backup…, Import Folder… (⇧⌘I), Import Lightroom Catalog…, Import CSV…, Export… (⇧⌘E), Export All… (the full export of the library), Prepare a Package for Vault… (see Package for Obscura Vault);
• Edit — Undo (⌘Z) and Redo (⇧⌘Z) (see below), Find… (⌘F), which puts the cursor in the search field of Works;
• View — Show Sidebar / Hide Sidebar (⌃⌘S), Show Inspector / Hide Inspector (⌥⌘I, in Library and Collections and search), Hide Works List (⌥⌘L) and Record in Full Window (⇧⌘F, in Works, see Room for the record);
• Go — Back (⌘[), Forward (⌘]), then the sections in the sidebar’s order, from Library (⌘1) to Imports (⌘9); Exports, Reports and Certificates have no shortcut;
• Help — Obscura Catalog Help (⌘?), Report a Problem….

Catalog has a single window: ⌘N creates a work, not a second window. The help article Menus and keyboard shortcuts goes through them in detail.

Undo and redo

Edit › Undo (⌘Z) and Redo (⇧⌘Z) reverse and repeat, and the menu says what (“Undo Rating”):

• typing in a record, an agent, an exhibition or a publication (typing in one field counts as one step), and Revert to the saved values. After Save, Undo puts the earlier value back in the record, marked “Modified”, without writing anything;
• the ratings, flags, colour labels and tags of files, adding to a collection and removing from one;
• a batch edit of works.

Deletions (work, agent, exhibition, publication, print, attribution, provenance, files removed from the catalogue, collection, tag), merging two agents, imports and restoring a backup cannot be undone: their confirmation says so.

Licence and free tier

Obscura Catalog can be used without a licence. At launch, while no account is signed in, the Activate Obscura Catalog window opens:

• sign in (Email address, Password, Sign in) with the account that holds your Obscura Catalog licence. Forgot password? sends a reset email;
• or click Continue without a licence: you keep the free tier, and the window no longer opens by itself. It stays in the Obscura Catalog › Activate Obscura Catalog… menu.

Without a licence, you can browse and search your libraries, describe up to 50 works, import files, a CSV and a Lightroom catalog (dry run and import), export CSV, print the catalogue raisonné and the portfolio, verify certificates and issue up to 10, and run the data checks. Your catalogue is never locked: nothing that reads it, or exports it in an open format, requires a licence.

What each plan includes:

These are the plan’s numbers: the licence server may adjust them for your account, and Account & Licence shows the ones that apply. The inventory reports come in a forthcoming version.

What is counted, exactly:

• Works: those of the open library’s catalogue, counted when you create them (one by one, from files, through a CSV import).
• Issued certificates: on this Mac, across all libraries, by number (a re-issue keeps its number and does not count twice; a revoked certificate still counts). A new library does not reset the count. When the server can be reached, its usage report is a cross-check: the larger of the two counts applies.
• Libraries: those created on this Mac that still exist, the standard library included. Only creating one is limited (File › New Library…, Settings › General › New library…): opening another library, browsing it, searching it and exporting it never is. A deleted library frees its place; a moved library keeps its own.

An Obscura Flow or Obscura Vault licence does not cover Obscura Catalog: each app has its own.

Once activated, the licence is also checked offline, for the period the server set or, failing that, 30 days after it was last confirmed. Past that, or if the Mac’s clock has been set back, the paid features wait for the Mac to connect to the Internet once; everything else keeps working.

When the licence refuses an action, Catalog says why (“The free tier allows 50 works; you already have 50.”) and what would unlock it, with Activate… to open the licence.

The last checked licence is kept on this Mac, in ~/Library/Application Support/com.oorun.obscuracatalog/License/, outside every library: a library copied to another Mac does not take your licence with it. It is only valid on the Mac it was checked for, only while an account is signed in, and Sign out erases it. At the first launch of this version, the licence kept until now in the library is moved there.

Account and licence

The licence button in the toolbar (“No licence”, “Pro Licence”…), the Obscura Catalog › Account & Licence… menu and the Account & Licence tab of the settings open the same screen:

• Account — the signed-in account, Check now (confirms the licence with the server), Sign out;
• What the licence includes — each feature, available or locked; the features “Included without a licence” are marked;
• Plan limits — works, issued certificates, libraries and devices, with the usage when the server can be reached;
• Devices — the Macs using the licence, this one marked This Mac. Revoke this device… frees another Mac’s seat; it will have to sign in again to use it. This Mac cannot be revoked from here: the server would refuse it for good.

Device limit reached

Each plan allows a number of devices. When this Mac is one too many (a new Mac, or a Mac too many after a change of plan), the server refuses it the licence: the paid features are locked, as for a blocked licence, but the session stays open and the free tier carries on. It is not an expired session: there is no need to sign in again.

Account & Licence says so at the top, with the figures: “Device limit reached: 3 devices on a plan that allows 2.” (or “Device limit reached: your plan allows 2 devices.” when the number of devices is not known), then the device list. A feature refused for this reason offers Manage devices…, which opens Account & Licence on that list.

The server grants the licence to the most recently seen devices: to free a seat, revoke one of the other Macs (Revoke this device…, then confirm). Catalog checks the licence again at once; if the seat is free, the paid features are unlocked again.

Settings

Obscura Catalog › Settings… (⌘,) gathers every setting of the app, one tab per area:

• General — the Library location; Show in Finder opens it; Move…, Open another library…, New library… (see Moving the library, keeping several libraries); the Language — System (that of macOS, the default), Français or English — which applies to the screens, the in-app help and the macOS menus from the next launch (Relaunch now applies it at once, after offering to save your edits in progress); the Appearance — System, Light or Dark — applied at once to every window;
• Catalogue — the Fonds (the name of the workspace, which can be renamed), Work numbering, Inventory numbers (optional) and the Publication threshold (see Setting up numbering), the Default confidentiality of new works, new prints and new provenance events, the Series defaults, and the Completeness weights, read-only;
• Files — for a folder import, the default choice for files already in the library, Pair each RAW with its JPEG (on by default) and Run the analysis after import (off by default); for metadata, Save metadata (the choice the editor opens with), and the Default creator and rights (see Default creator and rights);
• Faces & Analysis — Detect faces, and Erase… all the analysis data (see chapter 7);
• Certificates — the signing key, the issuer, the addresses and the notices (see Certificate settings);
• Exports — the default separator of CSV exports, the default author and paper of reports, and the source, base URI and language of LIDO and CIDOC records (see chapter 15);
• Backup — the library’s backups (see Backing up and restoring the library);
• Privacy — what leaves this Mac, the Confidential exports log (see Including confidential records), and Report a Problem…;
• Account & Licence — see above;
• Updates — the Installed version, the Automatically check for updates option and the Check for Updates… button (also in the Obscura Catalog menu).

The Settings… buttons of the screens (Works, Faces, Certificates, Imports, Exports) open the tab that concerns them. The Catalogue and Certificates tabs and the LIDO and CIDOC part of Exports are saved with Save (Revert drops the changes); the other settings apply as soon as you change them. The settings that belong to the library (fonds name, numbering, inventory numbers, threshold, default confidentiality, series defaults, certificates, LIDO and CIDOC records, confidential exports log) are saved with it and follow it into its backups; your default choices (Files, Faces & Analysis, Exports), the language and the appearance are preferences of your account on this Mac.

Looking for updates only works in the release distributed as a disk image, signed and notarized. A copy built from source shows “Automatic Updates Off in This Copy” and sends no request: install the disk image from the download page.

Where Catalog keeps its data

The library is a folder in your account:

~/Library/Application Support/Obscura Catalog/

It contains:

• Catalog.sqlite — the database: referenced files, metadata, collections, tags, thesaurus, people, works, agents, exhibitions, publications;
• Derivatives/ — thumbnails and previews, which can be recomputed at any time;
• Documents/ — the copies of the documents attached to files (invoices, correspondence, condition reports; see Attached documents) and to works or their prints (correspondence, archives, external certificates; see Documents): back it up with the database;
• catalogue-settings.json — the catalogue raisonné settings (numbering, inventory numbers, publication threshold, default confidentiality, catalogue introduction);
• export-settings.json — the source, base URI and language of LIDO and CIDOC records;
• certificate-settings.json — the certificate settings;
• Certificats/ — the PDFs of issued certificates;
• Backups/ — the library’s backups and their journal (see below);
• Catalog.lock — the lock that stops two copies of Obscura Catalog from opening the same library.

The certificate signing key and your account session are not in this folder: they are in the macOS keychain (see Certificates of authenticity). Nor is the licence: it is kept for this Mac in ~/Library/Application Support/com.oorun.obscuracatalog/License/. The app’s log, which Report a Problem… attaches, is in ~/Library/Logs/Obscura Catalog/.

Your images are never copied into this folder. Catalog records where they are. If you move or rename a folder in the Finder, or unplug a disk, Catalog can no longer find the files concerned (see Troubleshooting).

The only files Catalog writes next to your images are XMP sidecars, when you save metadata (see EXIF and XMP metadata).

Also copy this folder, backups included, to another disk with the rest of your data (Time Machine or other). Do not copy Catalog.sqlite alone while Catalog is open: the database is written in small steps to Catalog.sqlite-wal, and the copy would be incomplete. None of this replaces a backup of your images themselves.

Backing up and restoring the library

Catalog backs up its library itself, in the library’s Backups/ folder. Each backup is a dated folder holding:

• a consistent copy of the database, taken even while you work;
• the attached documents (Documents/), the PDFs of issued certificates (Certificats/) and the settings of the catalogue, the certificates and the LIDO and CIDOC records (catalogue-settings.json, certificate-settings.json, export-settings.json);
• a manifest (backup.json): the date, the Catalog version, the database schema and the SHA-256 of its copy.

Thumbnails (recomputed), the licence (checked again with the server), the signing key and the session (in the keychain) and your images are not in it.

A backup is written under a hidden name, verified (database intact, a schema this version reads), then published in one step: an interrupted backup (Mac switched off, disk full) never shows in the list and never replaces the previous one. Each backup, each failure and each restore is recorded in Backups/journal.jsonl.

Backing up. Catalog backs up automatically when the last backup is a day old: at launch, then once a day while it is open; Settings › Backup › Back up automatically (at launch, then once a day) turns it off. File › Back Up Library or Back up now backs up at once. Keep n backups (10 by default, from 2 to 50) sets how many are kept: beyond that, the oldest are removed. Show in Finder shows the backups folder. If the last backup failed, the tab says so, with the reason.

Compacting. SQLite never gives back to the disk the space a deletion frees: it keeps it for later writes. Settings › Backup › Compact the library takes a backup, then rewrites the database without that free space, and says its size before and after. It also happens on its own, right after an automatic backup, when more than a quarter of the database is free. Nothing is lost: the compaction is done in one go, and the database stays as it was if it fails.

Restoring. File › Restore a Backup… opens Settings › Backup. Choose a backup, then Restore… and confirm (“Restore this backup?”, Restore). Catalog checks the backup in full and refuses it if it is damaged, changed since, or written by a newer version; it offers to save your edits in progress; it sets the current library aside, in the list, as Before restore; it replaces the database, attached documents, certificates and settings; then it relaunches.

The certificate register never goes back. A certificate issued since the backup is a signed document in circulation, and a revocation or a key declared compromised must hold. So before restoring, Catalog compares the backup’s certificate register with the current one, and carries what is newer into the restored library: the certificates issued since (with their PDF), the revocations and replacements made since, the signing keys retired or declared compromised since. The confirmation names them. A number issued is thus never issued again for another work. If a certificate cannot be carried over (its number or its issuer exists in another form in the backup), the restore is refused before anything is touched, and the message names these certificates: choose a more recent backup. If the current register cannot be read (a damaged database), nothing can be carried from it: the confirmation says so, and the restore stays possible, since recovering the library comes first; then check the register in Certificates. To go back, restore the Before restore backup. An incomplete folder found in Backups/ (a copy made by hand, a backup cut short) is pointed out, never offered for a restore or deleted.

A damaged database. At every opening, Catalog checks the database. If it is damaged, Catalog does not open it and writes nothing to it: “The library database is damaged (SQLite: …). Nothing was written to it.” Then restore a backup in Settings › Backup.

Backups are on the same disk as the library: they protect against a mistake or a damaged database, not from losing the disk. Hence the copy of the folder to another disk, above.

A library opens in one copy of Obscura Catalog at a time: a second copy answers “This library is already open in another copy of Obscura Catalog”.

Running tasks. A restore, like a change of library, is refused while one of your tasks runs: an import (folder, Lightroom catalog, CSV of works, exhibitions or publications), an export (CSV, LIDO, CIDOC, full export) or a package for Vault. The message names it (“A task is running: the full export. Wait for it to finish or stop it, then try again.”). The preparation of thumbnails and the face analysis are stopped and waited for without asking: they resume later where they were. Quitting Catalog during one of your tasks first asks “A task is running”: Cancel lets it finish, Stop and quit stops it. A stopped import can be resumed or started again; a stopped export or package leaves nothing and has to be made again.

A backup copies the attached documents before the database, then checks that every document named by the database copy has its file there: a document attached or removed during the backup never leaves a row without its copy.

Moving the library, keeping several libraries

Moving. Settings › General › Move…, then Move in the confirmation (“Move the library?”), puts the library in the chosen folder (an external disk, for instance), in a folder of the same name. On the same disk, it is simply renamed. To another disk, the preparation of thumbnails and the face analysis are stopped first, so that nothing changes during the copy. The library is copied, the copy checked file by file (size, and SHA-256 for all but thumbnails), then opened at its destination the way Catalog opens a library. If anything differs, or if the copy does not open there (“The copy does not open at this location”), the copy is removed and the library stays where it was, whole. Otherwise the original goes to the Trash. Database, attached documents, certificates, thumbnails and backups go along. Catalog remembers the new place as soon as the files are there, then relaunches on the moved library. If the certificates’ PDF paths could not follow, the move stands all the same; the diagnostic log notes it.

A local disk, never a network volume or a synced folder. A library’s database is written with a journal that SQLite shares between the connections of a single Mac, and the lock that keeps two copies of Catalog from opening it together only holds on that Mac. On a network volume (a NAS, an SMB, AFP, NFS or WebDAV share), a dropped connection while saving may damage the database, and two Macs can open it without seeing each other. A synced folder (iCloud Drive, Google Drive, Dropbox, OneDrive, Box) copies the database and its journal separately, at its own pace: the library may reach the other Mac half written, or twice (“Catalog (1).sqlite”), and its confidential data ends up with a third party. So Catalog refuses to create or move a library there, and says why. A library already there still opens, but a warning says so at launch and in Settings › General; Move the library… leads to Move…. Backups and exports may go there: copying a backup to a NAS or a synced folder is safe, it is the library in use that must not be there.

Working on two Macs. Two safe ways:

• An external disk, on one Mac at a time. Move the library to an external SSD (Move…). Plug it into the Mac you work on; before unplugging it, quit Catalog (⌘Q), then eject the disk in the Finder. On the other Mac, use File › Open Library… the first time, then Catalog reopens it by itself. Never open it on both Macs at once over the network.
• One library per Mac. Each Mac keeps its own, on its disk. To hand the work over, back up (File › Back Up Library), copy the backup’s folder (in Backups/) to the other Mac’s disk, then open it there with File › Open Library…; or go through a full export. The copy may travel through a NAS or a synced folder, as long as it is opened from the Mac’s disk. Only one of the two libraries is the reference at a time: they do not merge.

If the disk is not plugged in at launch, Catalog does not create an empty library in its place: it says “The library cannot be found” (“The library could not be opened”), and Try again opens it once the disk is plugged in; you can also open another library in Settings › General.

Several libraries. One library per collection (an estate, a gallery): each has its own database, settings and backups.

• File › New Library… (or New library… in Settings › General) creates an empty library, in a new or empty folder;
• File › Open Library… (or Open another library… in Settings › General) opens a library folder (the one holding Catalog.sqlite); a library written by a newer version, damaged, or already open in another copy of Obscura Catalog is refused;
• Settings › General › Back to the default library, offered when another library is open, goes back to the one in your account’s folder (created empty if there is none); the library left stays where it is.

The certificates of a new library start from your last settings and from your signing key’s backup already confirmed; the issuer and the number prefix are to be confirmed for that library (see Another library on the same Mac).

A library opened on another Mac. The library references your images where they are, by their full path; it does not contain them. Copy the image folders along with it. If their path is not the same on the other Mac (another account name, a disk named differently), a banner above the Library grid points out each imported folder none of whose files can be found: Locate folder… relinks it to its new location, after checking each file by its fingerprint (see Locating a moved folder). Nothing changes without your confirmation.

When the OBSCURA_CATALOG_LIBRARY variable names the library (a test library), these commands are dimmed.

Catalog opens one library at a time. Each change first offers to save your edits in progress, then relaunches Catalog; the last library opened is opened again at the next launch. The account and the licence apply to all your libraries: the licence is kept on this Mac, not in the library. The licence limits how many libraries are created on this Mac (one without a licence, see Licence and free tier); New Library… says so before the panel opens, with Activate…. Opening another library is never limited.

Good to know

• Catalog does not need the network to work: face and likeness analysis runs on the Mac (see Faces and similar photos). It only connects to the licence server (signing in, checking the licence), to the update feed (unless you turn off Automatically check for updates and never check by hand), and to the certificate timestamp authority if you set one.
• Obscura Catalog is derived from Obscura Flow 2.0.8. It starts on a fresh database: it does not take over an Obscura Flow library.