dave/photolib
1
0
Fork 0
Code Issues 5 Pull Requests Releases Wiki Activity

update readme

Browse Source
This commit is contained in:
dave 2019-07-04 17:29:49 -07:00
parent d6743ad2a6
commit 022f4a90a7
1 changed files with 95 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
README.md
View File

@ -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.