Basic Use
Important note: Image Occlusion Enhanced has recently undergone a major update which means that most of the information provided in this Wiki only applies to the latest version. Please make sure to update your local add-on installation and read this section before proceeding.
Please refer to the following tutorial video for a general overview of the topics covered in this Wiki section:
Please understand that some of the points in the video might be out of date. You will always find the most recent information in this Wiki.
Video Errata for Image Occlusion ≥1.0.0
Occlusion modes
- The nonoverlapping occlusion type is now called Hide All, Reveal One
- The overlapping occlusion type is now called Hide One, Reveal All
- A new occlusion type called Hide All, Reveal All is now available. Functionally this one sits between the other two in that it hides all masks on the front, but also reveals all of them on the back.
Changing the image
You can now switch to a different image right from the IO Editor dialog. This won't clear any of your existing masks or field data, and is mostly meant as a quick way of switching to a different version of the same base image.
Work in progress
As this is a new feature in v1.0.0 there is no video covering this topic, yet.
Launching IO in Editing Mode
You can invoke IO's Editing mode by clicking on the IO button in Anki's browser or when editing a note from the Reviewer. Notes will only be editable if they fulfill all of the following criteria:
- Correct note type, i.e. Image Occlusion Enhanced
- A valid ID (Hidden) field
- A valid Original Mask field
Please see here for instructions on how you to convert older IO notes into editable notes.
Editing Notes
General princple
When editing a single note, all changes to the fields or masks will be propagated to all notes that were created alongside the current note when the note generation button was clicked ("sibling notes"). For changes specific to a single card, i.e. a single occluded item, you will have to use Anki's regular editing screens.
Important: Please don't modify any of the following fields when you are in Anki's Browser or Editing window:
- ID (hidden)
- Question Mask
- Answer Mask
- Original Mask
Modifications to these fields might break your notes and/or make them uneditable.
Important: Actions performed in Image Occlusion's Editing Mode cannot be easily undone, so please make sure to check your changes twice before applying them.
The only exception to this are purely textual changes to fields like the header or footer of your notes. These can be fully reverted by using Ctrl+Z in the Browser or Reviewer view.
Fields and Tags
This works as you would expect. Any changes to the entry fields will be applied to all sibling notes. If you want to exempt a specific field from being globally editable you can add it to the list of hidden fields in IO's Options dialog.
Masks
Each mask shape represents a card. Changes to the mask will edit the corresponding card in place, preserving its scheduling information. Removing any of the existing shapes will remove the corresponding card. New shapes will generate new cards.
New groups of existing shapes are treated as new shapes, each generating a new card while deleting all cards of the shapes that are now grouped. The same principle, only in reverse, applies to dissolving an existing group.
Occlusion Type
The add-on will use the original occlusion type by default. You can change this by using the dropdown box on the bottom left.
Image
Use the Change Image button on the bottom left to change the image. If the new image is bigger or smaller than the old one please make sure that your shapes don't end up outside of the canvas area. Otherwise cards with empty masks will be generated.
Deck
The Deck Selector only works for the Add New Cards button (see below). Please use Anki's Browser for changing the deck, as you would with any other type of note.
Creating New Note Batches
If you click on the Add New Cards button while in Editing Mode a completely new batch of cards will be generated, leaving your originals untouched.
When editing existing notes, Image Occlusion Enhanced will modify the corresponding mask files in place. Anki's support for detecting modified media files is somewhat limited, so you might run into instances where your changes won't sync straight away. These issues normally resolve themselves as you add new media files to your collection. If they don't, you might have to perform a one-way sync to AnkiWeb.
Another important detail to remember is that AnkiDroid and AnkiMobile cache image files within a session. This means that changes you've synced might not appear until restarting the app.
Memory use in general has been significantly improved with v1.0.0 - with the exception of the editing feature. Here is why:
Anki caches all image files by default, just like AnkiMobile and AnkiDroid do. The add-on works around this fact by forcing Anki to drop its image and web render cache after performing a mask edit. Unfortunately this seems to lead to about 10-15 MB of additional memory use with each successive editing session.
I have yet to figure out how to prevent this. Until then restarting Anki every now and then might be a good idea on older machines if you edit IO notes frequently.