From 022f4a90a774fa2fb1f9dc18f37bb23016deef5b Mon Sep 17 00:00:00 2001 From: dave Date: Thu, 4 Jul 2019 17:29:49 -0700 Subject: [PATCH] update readme --- README.md | 116 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 95 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 2fb307a..6528cc9 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,84 @@ -photolib +Photolib ======== Cloud-native photo and related media library software, with a focus for photography hobbyists. -TODO longer description +Photolib provides a simple, rich, and modern UI to manage your photo and video library. It can scale to host hundreds of +thousands of photos but is also light and simple enough to host just the couple photos you shoot with your smartphone. + +Photolib stores images as a logical "photoset". This allows identical images and metadata to be grouped into one item. +Many photographers shoot in multiple formats - that is, to produce multiple files per click of the shutter. A JPEG and +a RAW of some sort (Like Canon's CR2) is common. The primary idea behind Photolib's organization is that one click of a +camera shutter equals one photoset. + +When photos are imported - assuming they are done in the same batch - files are grouped based on their name and +extension, using rules that apply to almost every camera format. For example, a camera shooting under the "multiple +formats" mode described above would create, from one shot, `IMG_1234.JPG` and `IMG_1234.CR2`. Photolib would detect that +since these two images have the same file name (the `IMG_1234` part), they are the same photo and should be grouped into +a photoset. + +In addition to controls in the web interface, Photolib provides both a REST API and command-line tools to manage your +photo library. Installation ------------ -TODO +Pre-built releases are not currently available. See `Dockerfile` for a step-by-step installation from source. + +The general steps are: + +* `npm install` - install modules needed to build the frontend assets +* `grunt` - build the frontend assets +* `pip3 install -r requirements.txt` - install python dependencies +* `python3 setup.py install` - install Photolib and command line tools + +Note that the npm and grunt steps can be skipped if you're not planning to run the web UI (e.g. you want only the +command-line tools). Usage ----- -After installation, photolib provides a CLI tool, `photocli`. It can be used as follows: +After installation, run the server: + +* `photoappd --port 8080 --library ./library --database ./photos.db --cache ./cache` + +Arguments are as follows: + +* `--library ./library` - store the hosted image files under this directory +* `--database ./photos.db` - store the SQLite database in this directory +* `--cache ./cache` - use this directory as a cache for things like thumbnails +* `--port 8080` - listen on http on port 8080 + +Depending on your setup, the `photousers` command can be used to create a user account. Login information is necessary +to see images marked as private or upload images. + +* `photousers create -u dave -p mypassword` + +That's it - you've set up Photolib! Next steps from here would be to the other command line tools to import media. + +Besides browsing, most interaction with Photolib will be done using its CLI tool, `photocli`. Note that server address, +username, and password details need to be provided via flags not shown here to in a config file. See `photocli --help` +for more information. + + +Commands +-------- + +* `photocli ingest` - import new photos into the library: + + +``` +$ photocli ingest photos/*.jpg raws/*.cr2 +``` + +or add a new format to an existing photo: + +``` +$ photocli ingest -c 52679a30-cee4-45c4-8d83-80ee92242e1c photos/*.jpg +``` + * `photocli checkdupes` - scan files and print those not already in the library: @@ -27,28 +90,39 @@ d2c2c30ca4986d364026644881d667162031008e60aac6a69d7b18230b7ea98c source/2019-04 9d42859ed92d7fb978cf73b41293480e1eab03d2d3a14c185c4daf3a49d324ab source/2019-06-19 16.28.07.png ... -$ photocli -s http://localhost:8080 checkdupes --sha-files shas.txt - +$ photocli checkdupes --sha-files shas.txt ``` -TODO: support not using `--sha-files` - - -* `photocli ingest` - import new photos into the library: +TODO: support not using `--sha-files`. +This command, along with `ingest`, allows for fun tool combinations like so: ``` -$ photocli -s http://localhost:8080 ingest photos/*.jpg raws/*.cr2 - -... - +photocli checkdupes --sha-files shas.txt | xargs -d "\n" photocli -y ingest ``` -TODO: implement this +This would ingest all the files listed in `shas.txt` that aren't already in the database. -There is some non-obvious behavior in the ingest process that is important to understand. Many photographers shoot in -multiple formats, in the sense that one click of the shutter produces multiple formats. Jpeg and Raw is common. During -ingest, photocli assumes that files with the same filename are multiple formats of the same image. E.g., if you have -both `IMG_1234.JPG` and `IMG_1234.cr2`, the two images will be grouped in the library. This combination action is only -applied during ingest; images already in the library that happen to share a filename with a file being imported will -not be merged. To add a format to a photo already in the library, see `photocli addformat`. + +Roadmap +------- +- Stateless aka docker support + - Photo storage + - ~~Abstract the storage api~~ done + - ~~Standardize on API ingest~~ done + - Display and retrieval of images from the abstracted image store + - Database support + - Support any connection URI sqlalchemy is happy with + - Tune certain databases if their uri is detected (sqlite and threads lol) + - ~~Cache~~ done + - ~~Using the local fs seems fine?~~ done +- Option to cherrypy sessions - Redis? +- Flesh out CLI: + - Config that is saved somewhere + - Support additional fields on upload like title description tags etc + - delete features + - tag features + - modify features (tags & images) + +- Longer term ideas: + - "fast ingest" method that touches the db/storage directly. This would scale better than the API ingest.