A KOReader plugin to view "xray items", i.e. user defined explanations of persons and terms in single books or even entire series:
- This DX plugin was inspired by the X-ray system on Kindles (see explanation on Amazon X-Ray on Kindle | All you need to know - YouTube).
- "Terms" in Dynamic Xray (DX) can be names of things, entities, concepts, definitions, places, named events, names of literary or philosophical movements, and much more. It's all up to the imagination of the user...
- DX differs from the Kindle system in that the user can define items dynamically, while on Kindles these items are "baked into" the ebook.
- The advantage of the DX approach is that the user can dynamically add and modify items or link them to other items; the advantage of the Kindle approach is that it isn't error-prone.
- DX can produce false hits, because it uses matching of the words in ebook texts to determine whether Xray items are present. For example, DX will be in trouble if there are two or more persons with the same first name in a book; DX won't be able to differentiate between them. But in about 95% of cases, the matches shown will be correct.
- All interface texts can be translated by the user.
- Some hotkeys for buttons in DX dialogs can be configured by the user, from within KOReader. The Page Navigator can be called while reading an ebook, with Shift+X.
- The Page Navigator module now offers an extra side tab to quickly inspect Xray items which are linked to the items named in the page. From there can then edit them, view more details about them or search all their locations in the current ebook. You can see this feature in action in the videos section.
- The Page Navigator has an occurrences-per-chapter-histogram at the bottom.
- DX has a Series Manager for listing the books in a series. The items in this Manager have action buttons, for viewing large covers, descriptions, reading progress, annotations count, opening the e-book, etc. An example of this manager can be seen in the last image under Images.
- DX has a Reference Information viewer, in which a user can quickly inspect background information as provided in the e-book. But without having to visit the corresponding section in the e-book.
- DX also has a Glossary viewer, copied from the Glossary in the e-book. When the user longpresses a word in the e-book text which is in the Glossary, its explanation will be shown.
- Tip: the ImageBookmarks-plugin is an ideal companion to DX's Glossary and Reference Information viewers.
- DX under Android
- Use cases
- Installation
- Usage tips
- Glossary and Reference Information viewers
- DX in action
- DX Settings menu
- Problem solving
- Issues to fix
- Todos
- About the code
- Development history and usage
- Icons
- Tips for navigating through the code
- License
DX should now be also loadable under Android.
The user can use DX to keep track for an ebook or an entire series of many persons and terms, mark them as important, to see how they are linked to other items, what are their aliases, in which chapters they are mentioned and how frequent, etc.
The user can use DX for study: to keep track of entities, concepts, definitions, places, named events, names of literary or philosophical movements etc., to see how these are linked to each other, in which chapters they can be found and how frequent, etc.
-
Clone this repo somewhere. From there:
- For Android: copy the contents of all folders under "koreader-settings-folder" to the corresponding folders under the settings folder (almost always named "koreader") of your KOReader installation.
⚠️ NB: Don't overwrite entire folders in this target folder with the folders from the repository! The only folder which you can safely overwrite is "plugins/xraycontroller.koplugin".- NB 2: thanks to the patches DX applies to KOReader, the plugin XrayController will also be loaded from KOReader's settings folder...
- For Kobo/Kindle (if a .adds folder is present):
- copy the folder koreader-settings-folder/plugins/xraycontroller.koplugin to .adds/koreader/plugins
- For Android: copy the contents of all folders under "koreader-settings-folder" to the corresponding folders under the settings folder (almost always named "koreader") of your KOReader installation.
-
⚠️ It's especially important that you copy koreader-settings-folder/patches/2-xray-patches.lua:- For Android: to a subfolder "patches" in your KOReader settings folder!** Without this, DX won't be available in your installation.
- For Kobo/Kindle (if a .adds folder is present): to a subfolder (create if not exists) "patches" of .adds/koreader
- For Pocketbook to a subfolder (create if not exists) "patches" of /koreader
-
The "koreader-settings-folder" folder in this repository represents the settings folder of your koreader installation. In most cases, this target folder will be named "koreader". In its root you should find settings.reader.lua.
- For Pocketbook the program folder and the settings folder are one and the same: /koreader.
-
In that target folder, create a folder patches if it doesn't exist yet and copy koreader-settings-folder/patches/2-xray-patches.lua to that target patches folder.
-
Copy koreader-settings-folder/settings/settings_manager.lua to the settings subfolder of the koreader settings folder of your current installation (this folder should already be present and should contain many files, e.g. sqlite3-files for KOReader's databases).
-
⚠️ Check whether the database filename in your KOReader settings folder is "bookinfo_cache.sqlite3". If not, go through the additional steps listed in User has a database filename other than "bookinfo_cache.sqlite3" -
If you want to let KOReader's footer display Xray items counts (see image 1b... under Images), you'll have to manually edit readerfooter.lua (because it's not patchable). An example of this is provided in manual-file-edit-examples/readerfooter.lua. See the comments at the start of that file.
-
It is possible to add a button to the dictionary lookup results dialog, with which to add the looked-up word to the Xray items. This cannot be done via a patch, but requires a manual edit of dictquicklookup.lua. See manual-file-edit-examples/dictquicklookup.lua for an example.
-
It is
⚠️ highly recommended to let KOReader display its keyboard in compact mode, so you have enough space available for the multiple-field DX forms. You can enable this compact display mode from the main KOReader menu: Cog icon > Device > Keyboard > Keyboard appearance settings > enable checkbox "compact".
NB: icons specific for DX will be loaded from the xraycontroller.koplugin/xrayviews/icons folder.
Make sure the file 2-xray-patches.lua is present in your patches folder. It will probably almost never have to be updated, because the patching of your KOReader will de facto be done by plugins/xraycontroller.koplugin/dx-patches.lua (which will be called by 2-xray-patches.lua).
As of 2025-12-25 translations are now stored in the table xray_translations in the database. This table will be automatically created upon KOReader start. The translations are lazily stored in that table, only when requested.
This will make the code and updates much easier to maintain for me and for cloners... Users can translate texts in the TranslationsManager, which is reachable from the bubbles icon in the left half of title bar of the XraySettings dialog.
Via ReaderHighlight the user can select texts as quotes to be displayed in the quotes tab of the Item Viewer. This feature can be used to add a book index, or to quickly read especially moving or important passages, or for storing definitions from the book. You can see a picture of this feature in the Images section (image 05b...).
This tab also has a Quotes Manager, to be called with the floating speech bubble button. In this Manager you can view, edit or remove quotes. You could e.g. use this feature to add you own notes to individual quotes.
DX has global hotkeys for calling its main dialogs:
- Shift + H: show Xray Help information
- Shift + L: show Xray List
- Shift + M: show Series Manager
- Shift + X: show Xray Page Navigator
-
The user will have the most Kindle-like experience when in the XraySettings UI_mode is set to "page" and UI_mark_xray_items is set to true. In this case tappable star icons will be shown to the right side of Xray items in the e-book text. By tapping on those star icons the information for that Xray item will be shown in the Item Viewer.
-
Another way to have a Kindle-like experience is to open the Page Navigator. In this navigator all Xray items in a page will be marked bold, and they will be mentioned in a side panel. Tapping on items in the side panel will put an explanation of that item in the bottom panel. You can even filter the content of the Navigator for a specific Xray item, so it will only show pages which contain that item. With the Page Navigator, you can browse through pages and see all known Xray items marked bold there. In the side panel you can tap on items to show their explanation in the bottom panel. If you longpress the arrow buttons, PN will jump to the next/previous occurrence of the item in the e-book. You can show this navigator by:
- pressing Shift+X on your (BT) keyboard; I'm not sure if this'll work on all KOReader installations
- longpressing the lightning or star Xray markers in pages
- tapping in KOReader's main menu: most left icon > Dynamic Xray > Show Page Navigator
- assigning a gesture for "Show Xray Page Navigator" (in the Gestures menu under "Reflowable documents...") and then use this gesture.
- Tag-groups are items which share a tag with each other.
- You can view them grouped together in the 4th tab of the Xray Exporter.
- Tag-groups can be very handy to e.g. see all persons/terms belonging to one party in a conflict together, or to group logically linked items together.
- The Items List has a checkbox-button in the top left to quickly assign a tag to multiple items. See images 3b... and 3c... in this README.
With the export button in Page Navigator you open a popup with a list of all Xray items. Including stats and additional info per item. This list you can copy to the clipboard and then print, if you like, for usage next to your e-reader.
When you longpress an item in the side panel, a filter icon will appear on the left side of that item. From now on, while browsing forward or backwards, the Navigator will only show pages which contain that filtered item. Very handy for study purposes!
If you want to undo the filter, longpress the filtered item in the side panel once again.
- The patch file adds a button "+ Xray" to the popup dialog for text selections. With this button, you can add new Xray items from the text selection.
- From the list of Xray items (to which you can assign a gesture, for quickly showing it), you can view and edit items, or add new items, by tapping on the plus-icon in the dialog footer.
- When you select a longer text in the ebook and tap on "+ Xray", DX will set this text as the description of the new Xray item. You then only have to type its name in the field below the description.
- By clicking on lightning or star icons in the margins of ebook pages, you can call up an overview of Xray items in resp. the current page or the paragraph with the star icon.
- You can assign a gesture to quickly call up the list of all Xray items in the book or series: cog icon in the main KOReader menu → Taps and gestures → Gesture manager → Multiswipes → select a gesture → Reader → Show xray-items in this book/series
- In the same way, you can also attach a gesture to the action "Add a Xray item".
DX uses mostly buttons with only icons, so without explanatory labels. However, if a button contains a point on the right side of the icon, or a downwards pointing arrow on the left side, this means that you can trigger a popup with help information about the function of that button by longpressing it.
- An arrow means that a button has more than one action available upon longpress.
- A point signifies a one action button.
- These actions can then be executed by tapping on the buttons at the bottom of the help dialog.
- If you don't longpress the main button, which has the help information, but simply tap it, its main function will be immediately triggered.
- DX has a Reference Information popup, where the use can store information loaded from the e-book. This might e.g. be timeline-information for a book.
- If the information is contained in a HMTL list or table, the information can optionally be saved as such, for nicer presentation and better readability.
- The user can add texts from the e-book to the Reference Information by highlighting their start and end.
- The viewer can be called from the e-book with the hotkey Shift+R.
- TIP: The ImageBookmarks-plugin by bozo22 is an ideal companion to DX's Glossary and Reference Information viewers. With this plugin you can save multiple favorite images from any book and quickly inspect them later on with a gesture. E.g. very handy for images containing maps for the book you are reading...!
- DX has a Glossary popup, where the use can store a Glossary copied from the e-book.
- The Gossary text will be stored in plain-text format, to make it searchable.
- When the user longpresses a word in the e-book text an it's in the Glossary, the Glossary Viewer will show that entry with its explanation.
- The user can add texts from the e-book to the Glossary by highlighting their start and end.
- The viewer can be called from the e-book with the hotkey Shift+G.
01 Xray marker in page
01b Xray items counts in footer (see lightning icon). You'll have to manually modify ReaderFooter for this.
02 Xray info dialog after click on marker
02b Page Navigator, with info panel with explanations of Xray items in the page.
02c Page Navigator: hotkeys.
02d Tappable popup with linked items after longpressing a name in the ebook
03 Items List
03b Items List: enter tag for assignment to items
03c Items List: select items for tag assignment
03d Tag-group selector, callable with gesture or hotkey
03e Tag-group viewer
04 Item Viewer tab 1
05 Item Viewer tab 2
05b Item Viewer: quotes tab
05c Item Viewer: linked items tab
06 Item Editor tab 1
07 Item Editor tab 2
07b Larger field editor, called with edit button next to field. Handy for fields with longer content.
07c Editor tab 2: set Xray type from popup dialog: person, important person, term or important term.
08 Help info for buttons
09 Manage XraySettings in a tabbed interface.
09b Manage DX hotkeys.
09c Modify a DX hotkey
09b Interface translations list
10b Translations navigator
10c Editing a translation
10d Help info for translations editor
11 Series Manager with action buttons (NB: version in this repository will have fewer c.q. other buttons and icons than the ones depicted here, because they reflect functionality tied into my personal system)
- Open the KOReader main menu
- Go to most left main item → Dynamic Xray (NB: this item is positioned at the bottom of the items, so you might have to navigate to the next subpage) → Settings
- This same settings menu is also reachable through the cog icon at the top left of these four dialogs:
- the Xray items list
- the Xray Item Viewer
- the Xray Page Navigator
- the popup dialog after you clicked upon a lightning or a star marker in the text of the e-book
This lets the user know that somewhere in KOReader (maybe in DX, maybe in another plugin) an error occurred, which prevented DX from initializing. Alas, these error conditions are very hard to debug for me from a distance...
The default database filename in the KOReader settings dir will almost always be "bookinfo_cache.sqlite3". But apparently
- Go to the DX Settings menu
- Enter and save the correct database file name for your installation in the setting "database_filename".
- KOReader will automatically be reloaded and then create the xray_items table in your database.
- Currently none?
- Update the demo movies in the GitHub releases section.
- Base custom translations on indices instead of the texts they translate → continued usability of translations by the user much better protected, even when the actual text to be translated changes.
- It is possible to add an item to the KOReader footer to show the total count of Xray items for the current ebook. But alas, ReaderFooter as it is now is much too convoluted and heavily relies on local vars, which to my best knowledge makes patching impossible. You could of course directly modify ReaderFooter yourself, but you'd then have to re-do this upon every update. You'd have to edit this module in several places, the most important modification being to add this function to the functions already present in footerTextGeneratorMap:
xray_items = function()
local items_count = #DX.vd.item_table[1]
if items_count == 0 then
return ""
end
local KOR = require("extensions/kor")
return KOR.icons.lightning_bare .. items_count
end
- Dynamic Xray uses a stripped version of my personal extensions system for KOReader.
- DX is added by patching the stock KOReader code, so you don't have to modify the code of the basic KOReader version.
- The DX plugin is structured to resemble an MVC structure:
- M = XrayModel > data handlers: XrayDataLoader, XrayDataSaver, XrayFormsData, XraySettings, XrayTappedWords and XrayViewsData (extensions)
- V = XrayUI, XrayPageNavigator, XrayTranslations and XrayTranslationsManager, XrayDialogs and XrayButtons (extensions)
- C = XrayController (plugin)
- In xray-info.lua you can find some explanations for programmers about the inner workings of DX. This file doesn't have a function in the plugin, is meant to be purely informational.
- Since the KOR extensions system uses many heavily modified stock KOReader modules and widgets, these modified files are loaded instead of the stock versions from the subfolders "modules" and "widgets" under the "extensions" folder.
- DeepWiki.com has an extensive analysis of the DX system. See
.
See Dynamic Xray plugin · koreader/koreader · Discussion #12964 · GitHub for the development history of this plugin and for Dynamic Xray usage examples by screenprints and screencasts.
Most icons used by DX were downloaded from Online Webfonts, and some from SVG Repo. In some cases, I've renamed these icons, to clarify their function in DX.
-
Use a JetBrains IDE (e.g. PhpStorm) with the extensions EmmyLua and Better Highlights. With that you get clickable comments and very good type hints, which makes it much, much easier to navigate through the code.
-
Also, with Better Highlights, you can colorize comments differently depending on the use case, for much improved readability.
-
In Better Highlights settings set (( and )) as wikilink start and end - the default is [[ and ]] -, so you can add clickable comments to --(( )) lua commented blocks.
GNU General Public License (GPLv3): open source software, free to use, modify and distribute your version. Naming me as the author of the very first version would be nice. See license.md in this repository or https://www.gnu.org/licenses/gpl-3.0-standalone.html for more details of the license.