=head1 NAME App::PhotoDB - App to manage a collection of film cameras & lenses =head1 SYNOPSIS All usage of PhotoDB is via the interactive command line, which is launched by running photodb =head1 DESCRIPTION PhotoDB is an attempt to create a database for film photography that can be used to track cameras, lenses, accessories, films, negatives and prints, to fully catalogue a collection of photographic equipment as well as the pictures that are made with them. Read the CONCEPTS section for full details on the capabilities of PhotoDB. PhotoDB can also write EXIF tags to scanned images taken with film cameras, so they appear in your digital photo library with the correct metadata (time, date, focal length, geotag, etc). At the moment, the PhotoDB project is unfinished and the code continues to change unpredictably. Look for a tagged release in the future! The heart of PhotoDB is the MySQL/MariaDB backend database schema. This is the most complete part of the project and describes all the data that is recorded. The application is an interactive command-line tool to make it easier to add and edit data in the database. It is not a graphical interface or web application (but someone with the right enthusiasm and skills could use the logic I've already written to make a basic graphical interface quite quickly). PhotoDB should be able to run on pretty much any Linux distribution and MacOS as the Perl dependencies are portable. Soon there will be Docker support which will simplify installation and allow PhotoDB to run anywhere, including on Windows. The application is not *quite* feature-complete, so for now you may also need to edit parts of the database directly in some circumstances. You can access the raw database using the MySQL command line, by using an application such as L or L to obtain a GUI for manipulating the tables. =head1 CONCEPTS =head2 Introduction PhotoDB is a database and application for cataloguing film cameras, lenses, accessories, films, negatives and prints - as well a range of other information such as exhibitions, orders, and darkroom chemicals. It is also capable of writing EXIF tags to JPG files scanned from negatives and prints. PhotoDB is strictly governed by relational database principles which can make it seem fiddly and complicated to use, but this structured data gives PhotoDB its power. The data is all stored in a MySQL backend and managed by the PhotoDB app, which does its best to be helpful when adding data and hopefully hide most of the sharp edges from the user. This guide tries to explain the key concepts behind PhotoDB. It is not an exhaustive guide to every command available. To list all commands, run C. To list all subcommands available under a command, run (for example) C. Each subcommand has a brief explanation with it. =head2 User data Out of the box, PhotoDB is mostly empty, ready for you to enter your own data. However if you install PhotoDB in the recommended way, it comes with some pre- filled data e.g. about manufacturers, film emulsions, film sizes, metering modes, etc, to get you up and running faster. In many cases you'll want to add to this data to suit your own needs but you shouldn't need to edit anything that already exists. The command C has subcommands for adding various pieces of data. Normally, you shouldn't need to go out of your way to add this type of data, as PhotoDB will prompt you if you need to add any while adding cameras, lenses, films, etc. =head3 Unique identifiers Every object registered in PhotoDB (e.g. camera, lenses, films, negatives, etc) is allocated a unique ID number, starting at 1 and counting up. This number is used to reference other objects. This number is often prefixed with a C<#> for readability, e.g. _Film #99_. One exception where alternative naming is also used is for negatives. A negative might have an ID of #100 but it may also be referred to in the format 18/6, where 18 is the ID number of the film it belongs to, and 6 is the number of the frame, separated by a forward slash. This alternative system makes it easier to handle negatives in the darkroom. It is accepted in most places in PhotoDB where a negative ID is needed. =head3 Cameras and lenses Cameras and lenses are the central component of PhotoDB. Cameras and lenses can relate to each other in one of two ways: * directly, for fixed-lens cameras (e.g. compacts) * via a lens mount, for interchangeable-lens cameras (e.g. SLRs) You will be guided through questions when adding a new camera or lens by running C or C. When adding a fixed-lens camera you will be asked to give details about the lens at the same time, which is then associated only with that camera. When adding an interchangeable-lens camera, you only specify the lens mount. You can add lenses separately by running C, which are then available to use with any camera with the same mount. Cameras and lenses have properties of different types. Some are text (like the model name), some are numerical (like the maximum aperture of a lens), some are yes/no (like whether a lens has autofocus) and some are multiple choice (like the different metering modes a camera supports). =head3 Films and negatives If you use the cameras and lenses to take photographs, you'll want to start entering information about films and negatives into PhotoDB. The word _negatives_ is a bit misleading as it refers to any image taken with a camera, including slides - which are positive! PhotoDB lets you record a stash of films by running C, which you can then load into a camera with C. Films are associated with a camera. They can be developed with C and archived with C. When you take pictures, we recommend you take notes about your exposures using a smartphone app, a piece of paper, or what ever method suits you. Then you can enter the data into PhotoDB at a later date. Negatives are associated with films and inherit some of their properties from the film they belong to. Negatives are added by running C. Negatives are also associated with a lens, as on many cameras it is possible to change lens between exposures. =head3 Prints Whether you have a darkroom, or you get your negatives printed at a lab, PhotoDB can track your prints. Prints are associated with the negative they were made from. You'll be able to add other info about how the print was made. Prints are added by running C. You can also record orders for prints with C, view your printing to-do list with C and record sales of prints with C. =head3 Scans and tagging Scans refer to digital versions of negatives, slides or prints that can be made with a scanner or a digital camera. Each negative/slide/print can be scanned more than once. Each scan must be recorded separately. You can run C to manually add a scan to the database. PhotoDB needs you to set a directory on your computer for scans to be saved in. It prefers if its scans are the only thing in that directory. It is strongly recommended to make a directory just for scans of your negatives and prints, e.g. C or similar. If you access PhotoDB on more than one computer, you can configure a different directory on each computer. Under this directory, PhotoDB expects there to be a subdirectory for each film. There is no mandatory naming specification, but the preferred convention is the number of the film ID followed by a brief human-readable title, e.g. C<55 Holiday in Rome>. Inside each subdirectory individual scans should be named C<--.jpg>, for example C<55-3-img123.jpg> or C<55-3-Coliseum.jpg> where C<55> is the number of the film ID, C<3> is the frame number (as written on the edge of the film) and the rest can be anything you like. The scans should not be put inside another subdirectory. PhotoDB does not create these directories or the scans inside them. It is up to you to name the scans this way. However, if you stick to the above naming convention, PhotoDB will at least record your scans and associate them with the right negative, to save you too much tedious data entry. You can tell PhotoDB to search for and add scans automatically by running C. Once the scanned JPGs have been entered into the database and associated with negatives or prints, you can add EXIF tags to the JPGs - the same as would be automatically written to JPGs taken by a digital camera. Supported tags include date, caption, geotag, exposure data, etc. This allows you to use almost any digital photo management app to sort, browse, and view your images with ease. Use C to tag all scans of a single negative or C to tag all scans from an entire film. It is safe to run tag commands more than once, as PhotoDB will only add or update tags that have changed. =head3 Accessories PhotoDB allows you to track your collection of camera and lens accessories, too. There are several "special" kinds of accessories that have their own properties, commands and relationships, and there are general accessories with no special properties. You can create your own types of general accessory. Special types of accessory with their own properties include: =over =item * battery =item * filter =item * filter adapter =item * flash =item * meter =item * mount adapter =item * projector =item * teleconverter =back All of the above "special" accessories can be added to the database with C>. Types of general accessory with no special properties could include cases or straps. General accessories can be associated with cameras or lenses, or neither. Add new general accessories with C and add new categories of general accessories with C. =head1 Installing PhotoDB =head2 Install database backend A pre-requisite for PhotoDB is a functioning MySQL or MariaDB database instance. If you have access to an existing MySQL server, e.g. at a hosting provider, note down the details for connecting (hostname or IP address, username, password). Otherwise, consider installing a MySQL server locally on your computer. If you do this, the hostname will be C. Create an empty database schema and database user with a password for PhotoDB with sufficient privileges at least to SELECT, INSERT, UPDATE, DELETE, CREATE and DROP. Detailed instructions are beyond the scope of this document but a basic setup would be: create schema photodb; grant all privileges on photodb.* to photodb@localhost identified by 'password'; =head2 Install application frontend There are several different ways to install the application. Choose your favourite. Install PhotoDB from CPAN or from a source tarball. =head3 From CPAN 1. Use the C client (or an alternative, such as C) to install directly: cpan App::PhotoDB or cpanm App::PhotoDB =head3 From source 1. Grab the latest release tarball from the [Releases page](https://github.com/djjudas21/photodb/releases). It's the one with a name like C. 2. Install it with C: cpanm /path/tp/App-PhotoDB-0.00.tar.gz =head3 Docker Run PhotoDB on any platform, with Docker 1. Fetch the Docker image docker pull djjudas21/photodb 2. Run the image docker run -it --rm -v ~/.photodb:/root/.photodb --name photodb photodb =head2 Configure database connection There are three methods for connecting to the database: 1. Database and application on same computer 2. Database and application on different computers, connect via native MySQL 3. Database and application on different computers, connect via SSH tunnel The app and accessory scripts need to know how to connect to the database. The first time you run PhotoDB, you will be prompted to enter connection details for the database backend. If you need to edit the config in future, the config file is created at C. =head3 Tunnelling If the database is on a remote server and does not have the MySQL port (3306) open to receive connections, you will need to set up a tunnel. Run the command below, substituting in the correct hostname and username for the database server. ssh -L 3306:localhost:3306 -N @ Once the tunnel is established, you should be able to connect to the database on C<127.0.0.1:3306> and your connection will be tunnelled. Configure PhotoDB in the same way as if the database was local. You will need to re-establish the tunnel each time you wish to use PhotoDB. =head1 BUGS/CAVEATS/etc Report bugs in the L =head1 AUTHOR Jonathan Gazeley =head1 SEE ALSO =over =item * L =item * L =back =head1 COPYRIGHT and LICENSE