PhotoFS Usage

a quickstart guide
INDEX| USAGE| CHANGELOG

Usage (docs/usage.txt)

  Using PhotoFS
------------------------------------------------------------

Example Usage:

The first thing you'll probably want to do after installing is insert
some files.  Before that, though, you should create categories to put
them in.   Think about the types of data you want to store, and
categories which fit them.  For example, here are the top-level
categories I use:

  - art
  - dates  (files sorted by date)
  - events
  - other
  - people
  - pets
  - places
  - school
  - screenshots
  - trips
  - work

You can create these with the bin/insert.py script:

  % /home/photos/bin/insert.py -c people
  % /home/photos/bin/insert.py -c dates -d "files sorted by date"

I don't like to type all that, so I've created a link from
~/bin/photos.py -> /home/photos/bin/insert.py .  I'll use this for the
rest of the examples.

So, with a few categories, you should be ready to put in some pictures.
Say you took a bunch of photos at Joe's birthday party yesterday.  I'd
first create a few more categories...

  % photos.py -c dates/2003/10/17
  % photos.py -c events/bdays/joe-2003

It's worth noting that categories must be created one level at a time.
I originally made it create multiple levels at once, but found this made
me lose pictures when I mistyped the category name.  Typing "poeple/joe"
instead of "people/joe", and such.  This is less powerful, but also less
error-prone.  The commands above may need to be expanded as follows:

  % photos.py -c dates
  % photos.py -c dates/2003
  % photos.py -c dates/2003/10
  % photos.py -c dates/2003/10/17
  % photos.py -c events
  % photos.py -c events/bdays
  % photos.py -c events/bdays/joe-2003

Now you've got a couple categories for the files.  So put the files in:

  # go to the place you put your new pictures
  % cd ~/pics/camera/dump
  % photos.py -c events/bdays/joe-2003 -c dates/2003/10/17 *.jpg

Now each picture is accessible by date or by the event at which they
were taken.  But what about the people in the pictures?  It's nice to
have a category for each person, too:

  % photos.py -c people/joe
  % photos.py -c people/joe img_3931.jpg img_3935.jpg img_3936.jpg img_3937.jpg
  % photos.py -c people/susan
  % photos.py -c people/susan img_3932.jpg img_3935.jpg img_3938.jpg
  % photos.py -c people/greg
  % photos.py -c people/greg img_3933.jpg img_3934.jpg img_3935.jpg

If you already had categories for joe, susan, and greg, you can skip the
step of creating their categories first.

At this point, each picture is in several categories.  For example, the
file img_3935.jpg is a member of the following:

  - dates/2003/10/17
  - events/bdays/joe-2003
  - people/joe
  - people/greg
  - people/susan

This helps describe each picture according to whatever criteria you
like.  The date, event, people in the picture... and you could add any
other categories to it as well.  The categories are listed when you view
the file's details in a web browser.

But sometimes it's nice to describe a picture with text, too.  Let's say
you want to annotate some of those pictures.

  % photos.py img_3935.jpg -d 'everybody smile!'
  % photos.py img_3931.jpg -d "Joe opening his present from me"
  % photos.py img_3938.jpg -d "Susan took a dare"

And there's a funny story behind the present you gave Joe, so you want
to explain it in detail:

  % vim /home/photos/cat/people/joe/img_3931.jpg/.description.long

After finishing up the story about the gift, Susan tells you not to show
the saucy picture of her to anyone who wasn't at the party.  So you want
to restrict access to one of those pictures:

  % rm /home/photos/cat/people/susan/img_3938.jpg/.anonread
  % photos.py img_3938.jpg -r susan -r joe -r greg -r me

That way, only you, Susan, Joe, and Greg can see the picture.  The
insertion script automatically enables public read access to each file
and category it creates, unless you tell it not to with "-a 0".  To
reverse this setting, it's necessary to remove the anonymous read
permission from the file, and optionally specify a list of users allowed
to view it.

If you feel you're done inserting data, it's safe to delete your
original files:

  # go to the place your pictures were originally
  % cd ~/pics/camera/dump
  % rm *

This is optional, and won't free up space if your PhotoFS is on the same
filesystem, but it helps keep things tidy.  Personally, I keep them
around just in case I did something wrong.  I just move them to a
different directory where "inserted" images are kept.

Eventually you decide you're done and want to look at the album.  The
web server will need permission to generate thumbnail images first, so
you should fix up the permissions:

  % cd /home/photos
  % sudo bin/perms.sh

This could take a while on a large database, so you can narrow the
search:

  % sudo bin/perms.sh flat/*/*img_39??.jpg

You may also want to update the database statistics:

  % bin/count.sh
  % bin/genstats.py > cat/.description.long

Then browse your album:

  % mozilla http://mysite.com/photos/events/bdays/joe-2003/

The first time the page loads, it may be slow.  The web server generates
thumbnails as needed, and stores them for later.

While browsing, you notice that one of the pictures of Greg is really a
picture of Joe.  Oops!  Better put it into the correct place:

  % cd /home/photos/cat/people/greg
  % mv img_3934.jpg ../joe

You can also move other things around easily with standard tools:

  % cd /home/photos/cat
  % mv amusing/joe people/joe/funny

After you have moved files or categories around, it's a good idea to
regenerate the category caches.  This makes the "also in..." feature
work.  Normally, these caches are created during regular file insertion,
but if you move things around it's necessary to regenerate them.

  % cd /home/photos
  % bin/catgen.py

And then you may want to regenerate the statistics, too:

  % bin/count.sh ; bin/genstats.py > cat/.description.long

Keeping the statistics updated is entirely optional, and doesn't affect
PhotoFS operation.

The category caches are semi-optional, and only need to be kept
up-to-date if you want the "also in..." feature to work.

  
INDEX| USAGE| CHANGELOG
Last modified: January 11, 2005 @ 7:39 MST
Copyright (C) 1996-2017 Selene Scriven