Initial commit

1 files changed, 78 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..43c3627
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# iPhotoExtractor
+
+Copies pictures from an iPhoto library into a directory structure based on iPhoto events. For
+example:
+
+```
+.
+├── Christmas
+│   ├── IMG_0001.JPG
+│   ├── IMG_0002.JPG
+│   ├── IMG_0003.JPG
+│   └── Originals
+│       └── IMG_0002.JPG
+└── New Year's
+    ├── IMG_0004.JPG
+    └── IMG_0005.JPG
+```
+
+If a photo was modified by iPhoto, the modified version will appear in the main event directory and
+the original version will be copied to an `Originals` subdirectory.
+
+This was inspired by
+[gaetronik/iPhotoShotwell](https://github.com/gaetronik/iPhotoShotwell)
+and
+[fasaxc/shotwell-iphoto-import](https://github.com/fasaxc/shotwell-iphoto-import),
+but differs in two respects:
+
+1. Both scripts target the Linux-only
+   [Shotwell](https://gitlab.gnome.org/GNOME/shotwell/)
+   photo manager, whereas this produces a platform-independent directory tree; and
+2. Both scripts obtain album data from the `AlbumData.xml` file, whereas this reads the `SqEvents`
+   table from `iPhotoMain.db`. This was important in my case, because the events had been used as
+   albums and the actual albums were uselessly broad things like "Photos," "Last Import," etc.
+
+## Requirements
+
+Install the
+[.NET Core SDK](https://www.microsoft.com/net/download)
+(2.0 or newer) for your platform.
+
+## Usage
+
+Clone the repo and run like so:
+
+```bash
+git clone https://github.com/rdnlsmith/iPhotoExtractor.git
+cd iPhotoExtractor
+dotnet run extract '/path/to/iPhoto Library' '/path/to/output'
+```
+
+The output folder does not need to exist beforehand. In fact, it will display a warning if you do
+specify an existing directory.
+
+If you want to see what the final directory structure will look like without actually copying any
+files, run
+
+```bash
+dotnet run preview '/path/to/iPhoto Library' '/path/to/output'
+```
+
+## Limitations
+
+This program has only been tested with one iPhoto library, and I don't know what version of iPhoto
+produced it.
+
+This program ought to work on any platform supporting .NET Core, but it has only been tested on
+Ubuntu 18.04.
+
+The output of the `preview` command is not guaranteed to be entirely correct, as the `extract`
+command will append _e. g._ `(2)` to a file name if a file by that name already exists. This may
+occur since some of the modified photos in my library had multiple file paths.
+
+The `extract` command copies every photo, which means you need enough free disk space to duplicate
+your library. I might consider adding a `--destructive` flag to move photos instead of copying them.
+
+This program has already served its purpose, and I don't have any more iPhoto libraries to test it
+on, so I'm not likely to make further improvements for myself. If you use this program and run into
+problems, please open an issue and I will try to help.
\ No newline at end of file