diff --git a/documentation/database-layout.md b/documentation/database-layout.md index 0f65dbb2..451adfe7 100644 --- a/documentation/database-layout.md +++ b/documentation/database-layout.md @@ -1,473 +1,473 @@ -Image database overview for KPhotoAlbum +Image database overview for KPhotoAlbum {#database-layout} ======================================= Concepts -------- ### Fuzzy Dates ### KPhotoAlbum has the concept of fuzzy dates (or date intervals), which are defined by a start date and an end date (both include a timestamp). This helps for photos which have been digitized from an analog medium. When the exact timestamp is known, startDate equals endDate. ### Directory structure ### All images are expected to be located below a common root folder. The root folder is the one containing the index.xml database file. All file names in the index.xml file are relative to the root folder. ### Tags ### Tags (sometimes called Categories in KPhotoAlbum) are arranged in multiple independent hierarchies, i.e. there is no common root for all tags. Tag hierarchies are organized as DAGs (directed acyclic graphs). ### Additional metadata ### Exif information is stored in an sqlite database called `exif-info.db` in the image root folder. If the exif database is removed, it can be recreated from the image files. ### Thunmbnails ### Thumbnails are stored in packed form in `.thumbnails` in the image root folder. Thumbnails can be recreated from the image files. The packed format is much more efficient in terms of I/O than storing the thumbnails as individual image files in the filesystem. The thumbnails themselves are stored in JPEG format, packed into 32 MB container files named `thumb-`, with n starting from 0 and incrementing as needed. The size of the JPEG images is determined by the user's configuration choice. The choice of 32 MB is arbitrary, but it combines good I/O efficiency (many thumbnails per file and the ability to stream thumbnails efficiently) with backup efficiency (not modifying very large files constantly). There is no header, delimiter, or descriptor for the thumbnails in the container files; they require the index described below to be of use. Additionally, an index file named `thumbnailindex` contains an index allowing KPhotoAlbum to quickly locate the thumbnail for any given file. The thumbnailindex file is stored in binary form as implemented by QDataStream, as depicted below. The thumbnailindex cannot be regenerated from the thumbnail containers. ``` thumbnailindex | +-Header | +-File version (int, currently 4) | +-Current file (file index of last written thumbnail) being written to (int) | +-Current offset into current file, in bytes (int) | +-Total number of thumbnails indexed (int) | +-images | +-image | +-relative pathname (QString) | +-file index (int) | +-file offset (int) | +-thumbnail size (int) ``` index.xml --------- Below is a visualization of the DOM-Tree of the index.xml file. Attributes are within parenthesis, comments in square brackets. ### Version 3 ### Used in KPA v4.4 (and in KPA v4.5, if positionable tags are not used). ``` KPhotoAlbum | (version=3,compressed=1) | +-Categories | +-Category (name,icon,show,viewtype,thumbnailsize) | +-value (value, id) | +-images | +-image | (file, label, startDate, endDate, angle, md5sum, width, height) | (desctiption, stackId, stackOrder, rating, videoLength) [optional] | (#Categories.Category.name#=#Categories.Category.value.id#) [optional] | +-blocklist | +-block (file) | +-member-groups +-member (category,group-name,members) ``` ``` KPhotoAlbum | (version=3,compressed=0) | +-Categories | +-Category (name,icon,show,viewtype,thumbnailsize) | +-value (value, id) | +-images | +-image | (file, label, startDate, endDate, angle, md5sum, width, height) | (desctiption, stackId, stackOrder, rating, videoLength) [optional] | +-options | +-option(name=#Categories.Category.name#) | +-value(value=#Categories.Category.value.value#) | +-blocklist | +-block (file) | +-member-groups +-member (category,group-name,member) ``` ### Version 4 ### Used in KPA v4.5. ``` KPhotoAlbum | (version=4,compressed=1) | +-Categories | +-Category (name,icon,show,viewtype,thumbnailsize,positionable) | +-value (value, id) | +-images | +-image | (file, label, startDate, endDate, angle, md5sum, width, height) | (description, stackId, stackOrder, rating, videoLength) [optional] | (#Categories.Category.name#=#Categories.Category.value.id#) [optional] | +-options | +-option(name=#Categories.Category.name#) | +-value(value=#Categories.Category.value.value#, area="x y w h") | +-blocklist | +-block (file) | +-member-groups +-member (category,group-name,members) ``` ``` KPhotoAlbum | (version=4,compressed=0) | +-Categories | +-Category (name,icon,show,viewtype,thumbnailsize,positionable) | +-value (value, id) | +-images | +-image | (file, label, startDate, endDate, angle, md5sum, width, height) | (description, stackId, stackOrder, rating, videoLength) [optional] | +-options | +-option(name=#Categories.Category.name#) | +-value(value=#Categories.Category.value.value#, area="x y w h") | +-blocklist | +-block (file) | +-member-groups +-member (category,group-name,member) ``` #### Differences to version 3 #### * Tags can be positionable, i.e. the ```images.image.options.option.value``` elements may have an additional attribute ```area```. * In the compressed format, ```images.image``` tags may have sub-elements ```options.option.value```. This format is used only for category values when an area attribute is present. ### Version 5 ### Not used in an official release. ``` KPhotoAlbum | (version=5,compressed=1) | +-Categories | +-Category (name,icon,show,viewtype,thumbnailsize,positionable) | +-value | (value, id) | (birthDate) [optional] | +-images | +-image | (file, label, startDate, endDate, angle, md5sum, width, height) | (description, stackId, stackOrder, rating, videoLength) [optional] | (#Categories.Category.name#=#Categories.Category.value.id#) [optional] | +-options | +-option(name=#Categories.Category.name#) | +-value(value=#Categories.Category.value.value#, area="x y w h") | +-blocklist | +-block (file) | +-member-groups +-member (category,group-name,members) ``` ``` KPhotoAlbum | (version=5,compressed=0) | +-Categories | +-Category (name,icon,show,viewtype,thumbnailsize,positionable) | +-value | (value, id) | (birthDate) [optional] | +-images | +-image | (file, label, startDate, endDate, angle, md5sum, width, height) | (description, stackId, stackOrder, rating, videoLength) [optional] | +-options | +-option(name=#Categories.Category.name#) | +-value(value=#Categories.Category.value.value#, area="x y w h") | +-blocklist | +-block (file) | +-member-groups +-member (category,group-name,member) ``` #### Differences to version 4 #### * ```Categories.Category.value``` has an optional attribute ```birthDate``` ### Version 6 ### Used in KPA v4.6. Same structure as version 5. #### Differences to version 5 #### * The legacy categories Keywords, Persons and Locations are not handled special any more. Upon upgrade from an older version, "Persons" is renamed to "People", and "Locations" is renamed to "Places". * Older versions of KPhotoAlbum stored the standard categories (People, Places, Events, Folder, Tokens, Media Type and Keywords; those have a translation) as their respective localized versions. This lead to several problems if a non-English locale was used and has been fixed in v4.6. Along with this update, it was also necessary to move all thumbnails in the CategoryImages directory refering to the old names and fix the respective category names in kphotoalbumrc. * The GPS related image tags (gpsAlt, gpsLat, gpsLon and gpsPrec) have been removed and are now superseded by storing GPS data in the EXIF database. ### Version 7 ### Used in KPA v4.7 ``` KPhotoAlbum | (version=7, compressed=1) | +-Categories | +-Category | (name, icon, show, viewtype, thumbnailsize, positionable) | (meta) [optional] | +-value | (value, id) | (birthDate) [optional] | +-images | +-image | (file, label, startDate, endDate, angle, md5sum, width, height) | (description, stackId, stackOrder, rating, videoLength) [optional] | (#Categories.Category.name#=#Categories.Category.value.id#) [optional] | +-options | +-option(name=#Categories.Category.name#) | +-value(value=#Categories.Category.value.value#, area="x y w h") | +-blocklist | +-block (file) | +-member-groups +-member (category,group-name,members) ``` ``` KPhotoAlbum | (version=7, compressed=0) | +-Categories | +-Category | (name, icon, show, viewtype, thumbnailsize, positionable) | (meta) [optional] | +-value | (value, id) | (birthDate) [optional] | +-images | +-image | (file, label, startDate, endDate, angle, md5sum, width, height) | (description, stackId, stackOrder, rating, videoLength) [optional] | +-options | +-option(name=#Categories.Category.name#) | +-value(value=#Categories.Category.value.value#, area="x y w h") | +-blocklist | +-block (file) | +-member-groups +-member (category,group-name,member) ``` #### Differences to version 6 #### The concept of translatable "standard" categories led to a lot of problems when users started KPA with different locales. Some of them simply can't be solved, so we decided to remove translatable category names. Now, each category is stored with it's literal name. Added an additional optional "meta" attribute to the Category-tag, so that the "Tokens" category (a "special" category like "Folder", but stored in the database and thus causing the same translation problems like the old "standard" categories) can be marked as such and does not need to have a fixed name anymore. ### Version 8 ### Used in KPA v5.4 ``` KPhotoAlbum | (version=8, compressed=1) | +-Categories | +-Category | (name, icon, show, viewtype, thumbnailsize, positionable) | (meta) [optional] | +-value | (value, id) | (birthDate) [optional] | +-images | +-image | (file, startDate, md5sum, width, height) | (angle, description, endDate, label, rating, stackId, stackOrder, videoLength) [optional] | (#Categories.Category.name#=#Categories.Category.value.id#) [optional] | +-options | +-option(name=#Categories.Category.name#) | +-value(value=#Categories.Category.value.value#, area="x y w h") | +-blocklist | +-block (file) | +-member-groups +-member (category,group-name,members) ``` ``` KPhotoAlbum | (version=8, compressed=0) | +-Categories | +-Category | (name, icon, show, viewtype, thumbnailsize, positionable) | (meta) [optional] | +-value | (value, id) | (birthDate) [optional] | +-images | +-image | (file, startDate, md5sum, width, height) | (angle, description, endDate, label, rating, stackId, stackOrder, videoLength) [optional] | +-options | +-option(name=#Categories.Category.name#) | +-value(value=#Categories.Category.value.value#, area="x y w h") | +-blocklist | +-block (file) | +-member-groups +-member (category,group-name,member) ``` #### Differences to version 7 #### * ```images.image.angle``` is only saved when it differs from the default angle (0) * ```images.image.endDate``` is only saved when it differs from the start date * ```images.image.label``` is only saved when it differs from the default label ### Attribute values explained ### * blocklist - block + ```file``` Relative filename to ignore. * Categories - Category + ```icon```
XDG desktop icon name + ```name```
Category name + ```show```
```0|1``` - hide or show category in the viewer. + ```thumbnailsize```
Category-thumbnail size in pixel. + ```viewtype```
Appearance of list views in the browser. ```TreeView=0, ThumbedTreeView=1, IconView=2, ThumbedIconView=3``` + ```positionable``` (since version=4 / KPA v4.5)
```0|1``` - indicates whether this category can contain areas (positioned tags) or not. + ```meta``` (since version=7 / KPA v5.7)
Meta information that holds an unique id for special categories (so that they can be tracked when they are renamed for localization). + value * ```id```
Numerical tag id, unique within each Category. * ```value```
Tag name. * ```birthDate``` (since version=5 / KPA v4.6)
Birthdate (```yyyy-mm-dd```) of a person (but allowed on all categories). Is used to display the age of a person on an image. * images - image + ```angle```
Image rotation in degrees; between 0 and 359. + ```description```
Description field; Text. + ```endDate```
End date of the image (see fuzzy dates) (```yyyy-mm-dd[Thh:mm:ss]```, second optional part starts with uppercase 'T') + ```file```
Relative path to the image file. + ```gpsAlt``` (since KPA 3.1, deprecated in version=6 / KPA v4.6)
GPS altitude data, double. + ```gpsLat``` (since KPA 3.1, deprecated in version=6 / KPA v4.6)
GPS latitude data, double. + ```gpsLon``` (since KPA 3.1, deprecated in version=6 / KPA v4.6)
GPS longitude data, double. + ```gpsPrec``` (since KPA 3.1, deprecated in version=6 / KPA v4.6)
GPS precision data, integer (-1 for "no precision data"). + ```heigth```
Image height in pixel. + ```label```
Textual label assigned to the image + ```md5sum```
MD5 sum of the image file. + options * option - ```name```
Category name; matches one of ```Categories.Category.name``` - value + ```value```
Tag name; matches one of ```Categories.Category.value.value``` + ```area``` (since version=4 / KPA 4.5)
Positional information for the tag. X,Y (upper left corner), width, height; all values in pixel. + ```rating``` (since KPA 3.1)
Integer rating ("stars"), between 0 and 10. + ```stackId``` (since KPA 3.1)
Numerical stack ID; images with the same stackId are displayed as an image stack. Stack ID starts with 1. + ```stackOrder``` (since KPA 3.1)
Image position within a stack; only valid when stackId is set.
Unique within the same stack. Stack order starts with 1. + ```startDate```
Start date of the image (see fuzzy dates) (```yyyy-mm-dd[Thh:mm:ss]```, second optional part starts with uppercase 'T') + ```videoLength```
Length of the video in seconds; -1 if length is not known. Only applicable to video files. + ```width```
Image width in pixel. * member-groups - member + ```category```
Category name; matches one of ```Categories.Category.name``` + ```group-name```
Name of the group, may equal a Tag name and is usually displayed like a Tag name. + ```member``` (uncompressed format)
A single tag name. + ```members``` (compressed format)
Numerical tag ids, separated by comma. diff --git a/documentation/debug-output.md b/documentation/debug-output.md index dee00ccf..a54a113a 100644 --- a/documentation/debug-output.md +++ b/documentation/debug-output.md @@ -1,57 +1,57 @@ -# Getting KPhotoAlbum to print debug output +# Getting KPhotoAlbum to print debug output {#debug-output} KPhotoAlbum uses categorized logging. By default, only warning messages but no debug messages are emitted. To enable addditional output, you can either enable all debug output (```kphotoalbum*.debug=true```) or have more fine-grained control by using one or more logging categories listed below. ## Enable logging using a configuration file Create or edit the file ```QtProject/qtlogging.ini``` in the generic config location (usually ```~/.config```) containing the following: ```` [Rules] kphotoalbum.*.debug=true ```` ## Enable logging using an environment variable You can set the environment variable ```QT_LOGGING_RULES``` using the same syntax as in the configuration file. Rules are divided by semicolons. E.g. you can start KPhotoAlbum like this on the commandline: ```` export QT_LOGGING_RULES='kphotoalbum.*.debug=true' kphotoalbum ```` ## Logging Categories in KPhotoAlbum - ```kphotoalbum.AnnotationDialog``` - ```kphotoalbum.BackgroundJobs``` - ```kphotoalbum.BackgroundTaskManager``` - ```kphotoalbum.Browser``` - ```kphotoalbum.CategoryListView``` - ```kphotoalbum.DateBar``` - ```kphotoalbum.DB``` - ```kphotoalbum.DB.CategoryMatcher``` - ```kphotoalbum.DB.ImageScout``` - ```kphotoalbum.Exif``` - ```kphotoalbum.FastDir``` - ```kphotoalbum.HTMLGenerator``` - ```kphotoalbum.ImageManager``` - ```kphotoalbum.ImportExport``` - ```kphotoalbum.MainWindow``` - ```kphotoalbum.Map``` - ```kphotoalbum.Plugins``` - ```kphotoalbum.RemoteControl``` - ```kphotoalbum.Settings``` - ```kphotoalbum.ThumbnailView``` - ```kphotoalbum.timingInformation``` - ```kphotoalbum.Utilities``` - ```kphotoalbum.Viewer``` - ```kphotoalbum.XMLDB``` ## Further reading - https://doc.qt.io/qt-5/qloggingcategory.html#details diff --git a/documentation/mainpage.h b/documentation/mainpage.h index 8d77047c..627c0b43 100644 --- a/documentation/mainpage.h +++ b/documentation/mainpage.h @@ -1,41 +1,43 @@ //krazy:skip /** \mainpage Welcome to the KPhotoAlbum source code documentation, which is generated with doxygen. To generate your own copy, simply run doxygen in the kphotoalbum source directory. A few related pages that you should read: \li \ref coding-standards \li \ref phrase-book \li \ref videothumbnails + \li \ref debug-output - Logging categories used by KPhotoAlbum + \li \ref database-layout - Documentation for on-disk file formats (index.xml, thumbnail storage, etc.) KPhotoAlbum is split into a number of modules, each module is a directory of its own on the hard disk and a namespace in the source code. The following is a list of modules:

Main GUI component

\li \ref MainWindow - The main window and associated dialogs. \li \ref Browser - This is the browser where you narrow your way to the image you want to see. \li \ref ThumbnailView - The thumbnail viewer. \li \ref Viewer - The image/video viewer. \li \ref AnnotationDialog - This is the dialog where you tag your images (the one you get to using Ctrl+1 and Ctrl+2). \li \ref DateBar - The date bar at the bottom of the main screen.

Other GUI components

\li \ref ImportExport - Import/Export dialog and asscociated classes. \li \ref Settings - The Settings dialog and backend classes. \li \ref HTMLGenerator - The buildin HTML generator. \li \ref CategoryListView - This is the tree view used in the annotation dialog. \li \ref Exif - Exif related dialog and backend classes

Database backend

- \li \ref DB The abstract interface for the database backend. - \li \ref XMLDB The XML based database backend. + \li \ref DB - The abstract interface for the database backend. + \li \ref XMLDB - The XML based database backend.

Backend

\li \ref ImageManager - Thumbnail loader \li \ref Plugins - KIPI plug-in management \li \ref Utilities - Miscellaneous utility classes \li \ref BackgroundTaskManager \li \ref BackgroundJobs - Jobs for the BackgroundTaskManager */ // vi:expandtab:tabstop=4 shiftwidth=4: