diff --git a/doc/doxygen/extra-pages/developer_documentation/loading_card_pictures.md b/doc/doxygen/extra-pages/developer_documentation/loading_card_pictures.md index b30eaf3bb..c4c335b00 100644 --- a/doc/doxygen/extra-pages/developer_documentation/loading_card_pictures.md +++ b/doc/doxygen/extra-pages/developer_documentation/loading_card_pictures.md @@ -98,7 +98,7 @@ Clearing the network cache (CardPictureLoader::clearNetworkCache()) also clears Before any network request is issued, CardPictureLoaderWorker hands the ExactCard to CardPictureLoaderLocal, which tries to find a matching picture on disk. If a local picture is found, it is used and no network request is made. -CardPictureLoaderLocal searches two locations: +CardPictureLoaderLocal searches three locations: - The **CUSTOM folder** (`/CUSTOM/`). Every file in it is indexed recursively by its base name (both `baseName` and `completeBaseName`, so a file named `ExampleCard.jpg` is indexed as `ExampleCard`). The index is rebuilt @@ -106,24 +106,52 @@ CardPictureLoaderLocal searches two locations: client (changing the configured pictures directory only reassigns the search paths; the next timer tick rebuilds the index). - The **set-named subfolders** of the pictures directory: `//` and `/downloadedPics//`. +- The **root of the `downloadedPics` folder** (`/downloadedPics/`). The export naming schemes without a + set-folder part write their files straight into `downloadedPics/`, so this is where flat-scheme downloads and the + local overrides described below are matched. For each candidate folder, the loader generates file-name variants from the card's corrected name, set code, collector number and provider ID using the import naming schemes (Card Name + Provider ID, Card Name + Set + Collector, -Set + Collector + Card Name, Card Name + Set, Card Name), each tried with both `_` and `-` as separator. A file matches -if its name starts with one of the variants - the extension is free - and the first variant that yields a readable -image wins. For example, the file `Example Card_EXM_43.png` in the `EXM` set folder matches the card with -corrected name `Example Card`, set code `EXM` and collector number `43`. +Set + Collector + Card Name, Card Name + Set, Card Name), each tried with both `_` and `-` as separator. A file is +accepted when its name without the extension *equals* the variant exactly - the extension itself is free - and the +first variant that yields a readable image wins. For example, the file `Example Card_EXM_43.png` in the `EXM` set +folder matches the card with corrected name `Example Card`, set code `EXM` and collector number `43`. \attention The file-name variants use the *corrected* card name, so split cards are stored under their joined name: the "Example // Card" card is matched by a file named `ExampleCard.*`. -The naming schemes are duplicated in the user-facing page @ref custom_card_pictures, which also documents how to -set up a custom card database that provides pictures via the CUSTOM folder and the `picurl` printing property. +The naming schemes are also documented in the user-facing page @ref custom_card_pictures, which additionally covers +the CUSTOM folder workflow, `picurl` and download URL templates. When the filesystem cache method is selected on the "Storage" settings page, downloaded images are additionally written -into `/downloadedPics/` using the configured export naming scheme (as `.png` files). Existing files -are never overwritten, so a provider outage can permanently leave a wrong image in that folder until it is deleted -manually - the user-facing troubleshooting guide @ref fixing_card_pictures covers how to do this. +into `/downloadedPics/` using the configured export naming scheme (as `.png` files). The two export +schemes with a set-folder part (`Set Folder / Name + Provider ID` and `Set Folder / Name + Set Name + Collector`) write +into `downloadedPics//`; the three flat schemes write directly into `downloadedPics/`. Automatic cache writes +never overwrite an existing file, so a provider outage can permanently leave an outdated image in that folder until it +is deleted manually - the user-facing troubleshooting guide @ref fixing_card_pictures covers how to do this. Explicit +image overrides (see below) are the exception and always overwrite. + +# Local Image Overrides + +Beyond the generic on-disk lookup above, individual printings can be given explicit artwork that wins over every other +source without touching the CUSTOM folder or any download URL. This is the "Image Overrides" submenu of the context menu +that opens when you right-click a card in the deck editor's printing selector. + +- **Load Custom Image...** asks for a picture file and installs it for the card through + CardPictureLoader::saveCardImageToLocalStorage() with `allowOverwrite == true`. +- **One entry per alternate printing** (labeled ` `): selecting one hands the card to + CardPictureLoader::installPrintingOverride(), which resolves that printing's artwork - enqueueing a load and waiting + for the `CardInfo::pixmapUpdated` signal if it is not cached yet - and persists it for the card. +- **Clear Custom Image** calls CardPictureLoader::deleteAllLocalOverrides() to remove every stored override image of the + card, after which normal resolution resumes. The entry is only enabled while CardPictureLoader::hasLocalOverrides() + reports at least one stored file. + +Overrides are stored as `.png` files in `downloadedPics/` under the export naming scheme configured on the "Storage" +settings page - which is exactly why the local matcher also looks into the `downloadedPics/` root (see above). They are +written with `allowOverwrite == true`, so an override always replaces whatever the filesystem cache previously saved for +that spelling; only *automatic* cache writes are prevented from clobbering it. Overriding a card with its own current +printing is a no-op (the UI omits it from the menu), and an override whose artwork fails to resolve surfaces the +"failed" card back instead of a silent no-op while any override already on disk is left in place and re-displayed. # URL Generation and Resolution @@ -141,21 +169,12 @@ For each set, CardPictureToLoad::populateSetUrls() builds an ordered URL list: 2. The configured download URL templates, in priority order (Deck Editor → "URL Download Priority"). URL templates are transformed into concrete URLs by CardPictureToLoad::transformUrl(), which substitutes reference -points. The following placeholders are available: +points. `!name!`, `!setcode!` and friends substitute card and printing data, while the `!set:!` and +`!prop:!` reference points resolve a property of the printing or of the card respectively. The canonical list +of all reference points with examples, including the `_fill_with_` and `_substr_` modifiers, lives in +@ref custom_card_pictures. -| Placeholder | Description | Example | -| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -| `!name!` | Card name | `Example Card` | -| `!name_lower!` | Card name, lower case | `example card` | -| `!corrected_name!` | Corrected card name | `ExampleCard` (instead of "Example // Card") | -| `!corrected_name_lower!` | Corrected card name, lower case | `examplecard` | -| `!sflang!` | Scryfall language code for the current client language; defaults to English when the language has no localized images | `en`, `zhs` | -| `!setcode!` / `!setcode_lower!` | Set code | `EXM` / `exm` | -| `!setname!` / `!setname_lower!` | Full set name | `Exemplary Set` / `exemplary set` | -| `!set:!` | A property of this printing, e.g. `muid` (Gatherer multiverse ID), `uuid` (Scryfall UUID), `num` (collector number), `rarity` | `373549` | -| `!prop:!` | A property of the card, e.g. `side` (front/back), `colors`, `cmc`, `coloridentity`, `type`, `pt`, and the format legality statuses | `front` | - -The `!set:...!` and `!prop:...!` placeholders also support two modifiers: +The `!set:...!` and `!prop:...!` reference points also support two modifiers: - `_fill_with_` pads the value with the given text, right-aligned, e.g. `!set:num_fill_with_000!` turns collector number `1` into `001`. If the value is longer than the fill text, the template is invalidated. diff --git a/doc/doxygen/extra-pages/user_documentation/card_pictures/custom_card_pictures.md b/doc/doxygen/extra-pages/user_documentation/card_pictures/custom_card_pictures.md index 9b354fbf6..98f245848 100644 --- a/doc/doxygen/extra-pages/user_documentation/card_pictures/custom_card_pictures.md +++ b/doc/doxygen/extra-pages/user_documentation/card_pictures/custom_card_pictures.md @@ -1,10 +1,11 @@ @page custom_card_pictures Custom Card Pictures -There are three ways to make Cockatrice use custom artwork for your cards: +There are four ways to make Cockatrice use custom artwork for your cards: - Placing image files in the **CUSTOM pictures folder**. - Providing a **custom card database** that points each printing at a picture URL via the `picurl` property. - Writing your **own download URL templates**. +- Setting an **image override** for a single card from inside the deck editor. Each of these is described below. If pictures are missing or wrong, see @ref fixing_card_pictures instead. @@ -109,3 +110,26 @@ wiki for more examples and ideas. \attention Keep in mind that templates using `!name!` or `!set:muid!` resolve by name or multiverse ID, not by the exact printing. Only the Scryfall `!set:uuid!` templates always return the exact printing requested. See @ref fixing_card_pictures for more on this. + +# Image Overrides + +The quickest way to give one card custom art is an image override: right-click the card in the deck editor's printing +selector and open the **Image Overrides** submenu of the context menu. + +- **Load Custom Image...** — choose a picture file (the dialog suggests PNG, JPG/JPEG and WebP); it becomes that card's + artwork immediately. +- **One entry per alternate printing** of the card, labeled ` ` (hovering an entry previews that + printing's artwork). Selecting one makes the card use that exact printing's picture, so e.g. a basic land can be shown + with any of its artworks. +- **Clear Custom Image** — removes the stored override and returns the card to normal resolution. It is only available + while the card has a stored override. + +Overrides are stored as `.png` files in `/downloadedPics/`, under the "Naming scheme" configured on +the Storage settings page, and are matched the same way as downloaded images. Because local files are checked before any +URL is requested, an override always wins over downloaded artwork and `picurl` for that card. The override exists only on +the machine it was created on - it is not part of the deck file - so a card with a stored override shows normally on +another computer. + +\attention If you also keep a matching file in the CUSTOM folder, that file is matched before the override. When you +change an override, use **Clear Custom Image** so the stored `.png` is replaced; manually deleting the file in +`downloadedPics/` has the same effect. diff --git a/doc/doxygen/extra-pages/user_documentation/troubleshooting/fixing_card_pictures.md b/doc/doxygen/extra-pages/user_documentation/troubleshooting/fixing_card_pictures.md index abdf4a291..7f761c020 100644 --- a/doc/doxygen/extra-pages/user_documentation/troubleshooting/fixing_card_pictures.md +++ b/doc/doxygen/extra-pages/user_documentation/troubleshooting/fixing_card_pictures.md @@ -28,7 +28,7 @@ valid URLs. If you suspect the list has been modified or corrupted, press 'Reset defaults. For information on how to add your own custom URL templates, see the 'How to add a custom URL' link in the same -settings section, or @subpage custom_card_pictures for a full reference of the URL reference points, the CUSTOM +settings section, or @ref custom_card_pictures for a full reference of the URL reference points, the CUSTOM pictures folder, and custom card databases. # Check Your Local Picture Folder @@ -42,6 +42,9 @@ Cockatrice checks the following locations, in order: - The custom pictures folder (recursively indexed by file name). - `//` - `/downloadedPics//` +- `/downloadedPics/` (for export naming schemes without a set folder) + +A file only matches when its name without the extension equals one of the recognized scheme patterns exactly. The following import naming schemes are recognized (using both `_` and `-` as separators). The canonical table with concrete example file names is on @ref custom_card_pictures: @@ -58,6 +61,10 @@ If a picture you downloaded or placed manually is wrong, stale, or corrupted, de attention to the `downloadedPics` subfolder: this is where the filesystem caching method writes downloaded images, and after a provider outage it can permanently contain the wrong printing until you delete it manually. +If a card persistently shows artwork you assigned yourself, you may have an **image override** set for it. Right-click +the card in the deck editor's printing selector and use 'Image Overrides' → 'Clear Custom Image' to remove it (or +delete the stored `.png` in `downloadedPics/`). See @ref custom_card_pictures for details. + See @ref loading_card_pictures for details on how local images are loaded. # Clear Caches