From d1d654ebac2d51e3841675faeb56480e440f622f Mon Sep 17 00:00:00 2001 From: Wolfgang Müller Date: Tue, 5 Mar 2024 18:08:09 +0100 Subject: Initial commit --- docs/advanced/api.rst | 14 ++++++++++ docs/advanced/hashing.rst | 15 +++++++++++ docs/advanced/image-processing.rst | 19 ++++++++++++++ docs/advanced/import-process.rst | 53 ++++++++++++++++++++++++++++++++++++++ docs/advanced/index.rst | 13 ++++++++++ 5 files changed, 114 insertions(+) create mode 100644 docs/advanced/api.rst create mode 100644 docs/advanced/hashing.rst create mode 100644 docs/advanced/image-processing.rst create mode 100644 docs/advanced/import-process.rst create mode 100644 docs/advanced/index.rst (limited to 'docs/advanced') diff --git a/docs/advanced/api.rst b/docs/advanced/api.rst new file mode 100644 index 0000000..61f6d01 --- /dev/null +++ b/docs/advanced/api.rst @@ -0,0 +1,14 @@ +GraphQL API & Versioning +======================== + +**hircine** exposes the `GraphQL `_ endpoint on `/graphql +`_. When accessing this documentation on a running instance, clicking +that link will open an interactive GraphQL IDE with a built-in documentation +explorer. + +Versioning +---------- + +**hircine** uses `Semantic Versioning `_. The *public API* +consists of both the frontend (command-line interface and web application) and +the backend (GraphQL API and plugin infrastructure). diff --git a/docs/advanced/hashing.rst b/docs/advanced/hashing.rst new file mode 100644 index 0000000..90da3db --- /dev/null +++ b/docs/advanced/hashing.rst @@ -0,0 +1,15 @@ +Hashing +======= + +**hircine** uses the `BLAKE3 cryptographic hash function +`_ to compute hashes of archives and all +its contained files. + +Whilst the latter files are hashed directly (i.e. their data is passed directly +to the hash function), the *ZIP* archives are not. Instead, **hircine** +calculates the hash of an archive by concatenating the hashes of *all* files +within it in archive order. + +This means that changes to the archive files themselves will invalidate an +archive's hash, but changes to *ZIP* compression levels or other basic metadata +will not. diff --git a/docs/advanced/image-processing.rst b/docs/advanced/image-processing.rst new file mode 100644 index 0000000..dba71d0 --- /dev/null +++ b/docs/advanced/image-processing.rst @@ -0,0 +1,19 @@ +Image processing +================ + +Images are processed by the `Python Imaging Library (Pillow) +`_ which supports a `wide +variety +`_ of +image formats. Processed images are stored in the :ref:`overview-object-store` +using the `webp `_ format. Images are +resampled using a `Lanczos filter +`_. + +Scaling +------- + +By default, images are scaled to fit within the bounds of ``4200x2000`` pixels +for display in the reader, and ``1680x800`` pixels for use as thumbnails. These +values are optimized for larger displays and may be :ref:`changed in the +configuration file ` if you do not require such high resolutions. diff --git a/docs/advanced/import-process.rst b/docs/advanced/import-process.rst new file mode 100644 index 0000000..b33a927 --- /dev/null +++ b/docs/advanced/import-process.rst @@ -0,0 +1,53 @@ +Import process +============== + +When importing a new archive, **hircine** will do the following: + +1. Calculate the hash of the archive its contents. See :doc:`/advanced/hashing`. +2. Process each image for display in the application. See :doc:`/advanced/image-processing`. +3. Collate all images in the archive in "natural" sort order. See `natsort + `_. +4. Add the images and archive to the database. + +Status display +-------------- + +For each new or updated archive, **hircine** will report its status on the +command line: + ++---------+--------------------------------------------------------------------+ +| Symbol | Meaning | ++=========+====================================================================+ +| ``[+]`` | This is a new archive. | ++---------+--------------------------------------------------------------------+ +| ``[*]`` | This archive was updated (i.e. its modified time has changed). | ++---------+--------------------------------------------------------------------+ +| ``[>]`` | This archive has been renamed. | ++---------+--------------------------------------------------------------------+ +| ``[I]`` | This archive was ignored as it is a duplicate. | ++---------+--------------------------------------------------------------------+ +| ``[!]`` | This archive conflicts with another archive. | ++---------+--------------------------------------------------------------------+ +| ``[?]`` | This archive is referenced in the database but could not be found. | ++---------+--------------------------------------------------------------------+ +| ``[~]`` | The images from this archive were reprocessed. | ++---------+--------------------------------------------------------------------+ + + + +Duplicates +---------- + +**hircine** will not add duplicate archives to its database. If two or more +archives have the same content (i.e. their hashes match), a warning will be +issued. + +Conflicts +--------- + +A conflict occurs when an archive hash in the database no longer matches the +hash of the archive file on disk. **hircine** will take no further action other +than printing an error message including the path of the archive and both +hashes; it is up to the user to reconcile conflicts. An easy (but destructive) +solution is to delete the affected archive in the web application and +reimport it. diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst new file mode 100644 index 0000000..3300030 --- /dev/null +++ b/docs/advanced/index.rst @@ -0,0 +1,13 @@ +Advanced topics +=============== + +This section describes advanced topics that are not crucial for usage of +**hircine**, but may nevertheless be of interest. + +.. toctree:: + :maxdepth: 1 + + import-process + hashing + image-processing + api -- cgit v1.2.3-2-gb3c3