commit ee013d9bf7fa4e4c1ebd1db6c186f008901667f9
parent 5f31b8c863b9b0bedcb294e0afb87d6dd2ee7d74
Author: René Wagner <rwagner@rw-net.de>
Date: Mon, 17 Aug 2020 19:41:57 +0200
major overhaul of README and --help output
Diffstat:
| M | README.md | | | 112 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------------- |
| M | phosta.pl | | | 15 | ++++++++++++--- |
2 files changed, 100 insertions(+), 27 deletions(-)
diff --git a/README.md b/README.md
@@ -33,31 +33,95 @@ Additionally the following perl modules need to be installed:
- Perl::DBI
- Text::SimpleTable::AutoWidth
+## features
+- loading of EXIF data from media files to a self-contained database
+- querying different statistics from the gathered data
+- available fields
+ - camera maker
+ - camera model (body)
+ - lens model
+ - focal length
+ - iso
+ - aperture
+- grouping with summarizing based on date&time of pictures
+ - year
+ - month
+ - week
+ - hour
+- filtering of data by
+ - time range of photos shot
+- custom sorting of output by arbitrary fields
+- output results in a table view to your terminal
+
+### example output
+```
+Querying database ~/photos.db with 82 entries...
+
+.-----------------+-------+---------.
+| model | count | percent |
++-----------------+-------+---------+
+| SM-A320FL | 31 | 37.8% |
+| Nokia 2.2 | 18 | 22.0% |
+| XF10 | 15 | 18.3% |
+| - | 9 | 11.0% |
+| STH100-2 | 3 | 3.7% |
+| iPhone SE | 1 | 1.2% |
+| PENTAX KP | 1 | 1.2% |
+| PENTAX K-5 II s | 1 | 1.2% |
+| PENTAX K-3 II | 1 | 1.2% |
+| PENTAX K-01 | 1 | 1.2% |
+| GR II | 1 | 1.2% |
+'-----------------+-------+---------'
+```
+
## usage
-### populate the database
-Before getting in touch with the stats, you need to populate the database with the data of your images. Run `phosta[.pl] -p <your_image_folder>` to add the data of the images in the folder and every subfolder to the database.
-
-The database will be created in the current working dir or at a given place. Be sure that you have write permissions in the respective folder.
-
-### query the database
-To query the stats, simply run `phosta[.pl] -s <fields> -g <grouping>` after you've initially filled the database.
-
-For information about parameters and usage call `phosta[.pl] --help`.
-
-### available stats
-- pictures by lens
-- pictures by camera body
-- pictures by shutterspeed used
-- pictures by focal length (35mm) used
-- pictures by iso used
-- pictures by aperture used
-
-The stats are available as grouped counts by
-- all time total
-- by year
-- by month
-- by week of year
-- by time of day
+Before you can query some stats, the EXIF data has to be extracted from your media files and written to the database. For available params and examples see the listing below.
+
+You can add different folders one by another to the database, the import will take care the files added and avoid duplicates (currently based on file path). If you think something is messed up you can clean your database and start over.
+
+After you've added some data, you can query different statistics which might be interesting. There are no predefined stats, instead you have the option to adjust the output to your needs using the different params listed below. More sophisticated filters (based on selected fields or file path) may come later.
+
+
+```
+usage: phosta(.pl) [options]
+
+generic options:
+ -D <file> : path and name of the db file to use, defaults to <workingdir>/photo_stats.db
+ This option is automatically saved in the user conf, you can omit this option if you always use the same db
+ -c : clear the database
+ -v : be verbose - print some debug output
+ --help : show this help
+
+data gathering:
+ -p <folder> : populate database from the files in the specified folder
+ Media files in the given folder and every subfolder are scanned, EXIF data extracted and pulled into the database
+ -E <ext> : list of comma separated extensions used for scanning image files, defaults to jpg,jpeg
+ only media files which match (case-insensitive!) the given extensions are added to the database
+ This option is saved to the user conf
+
+stats querying:
+ -g : group by time range, defaults to total (which means no grouping by time range)
+ allowed values: year, month, week, hour
+ -s <fields> : specify the information you want to select, defaults to none (just show number of images)
+ allowed values: maker, model, lensmake, lens, aperture, exposuretime, iso, focallength, focallength35mm
+ multiple fields should be listed comma-separated
+ -t <range> : only take images into account which have been taken in the given timerange
+ <range> must be specified as 'YYYYMMDD-YYYYMMDD', you can omit one value
+ -n <number> : limit the resultset to <number> of lines
+ -o <fields> : sort your output by the given fields (sequence matters!) in descending order
+ allowed values: any comma separated combination of the values of -t and -s param and 'count'
+ -r : sort in reverse (ascending) order
+
+examples:
+ phosta -E jpg,jpeg,tiff -D ~/Documents/stats.db -p ~/Pictures
+ load EXIF data of files with the extensions jpg, jpeg and tiff in folder ~/Pictures to the database located in ~/Documents/stats.db
+
+ phosta -s model -g month -t 20190101-20121231 -o month,count
+ show number of pictures taken with a specific camera body in 2019 grouped by month, sorted by newest month first
+
+ phosta -n 10 -s lens -o count
+ show top 10 lenses used the most over all pictures taken
+```
## FAQ
- I have my images on a network share, how can i include them into the stats?
diff --git a/phosta.pl b/phosta.pl
@@ -294,8 +294,7 @@ sub main::VERSION_MESSAGE()
sub main::HELP_MESSAGE
{
say '';
- say 'Extract the EXIF data of images (currently jpg only) and feed them to a database.';
- say 'Afterwards query some stats from the selected data.';
+ say 'EXIF data extraction for media tools and stats querying for your terminal.';
say '';
say 'usage: phosta(.pl) [options]';
say '';
@@ -314,7 +313,7 @@ sub main::HELP_MESSAGE
say ' This option is saved to the user conf';
say '';
say 'stats querying:';
- say ' -g : group by time range, defaults to total (which means no grouping by time range)';
+ say ' -g <period> : group by a time period, defaults to total (which means no grouping by period)';
say ' allowed values: year, month, week, hour';
say ' -s <fields> : specify the information you want to select, defaults to none (just show number of images)';
say ' allowed values: maker, model, lensmake, lens, aperture, exposuretime, iso, focallength, focallength35mm';
@@ -325,4 +324,14 @@ sub main::HELP_MESSAGE
say ' -o <fields> : sort your output by the given fields (sequence matters!) in descending order';
say ' allowed values: any comma separated combination of the values of -t and -s param and \'count\'';
say ' -r : sort in reverse (ascending) order';
+ say '';
+ say 'examples:';
+ say ' phosta -E jpg,jpeg,tiff -D ~/Documents/stats.db -p ~/Pictures';
+ say ' load EXIF data of files with the extensions jpg, jpeg and tiff in folder ~/Pictures to the database located in ~/Documents/stats.db';
+ say '';
+ say ' phosta -s model -g month -t 20190101-20121231 -o month,count';
+ say ' show number of pictures taken in with a specific camera body in 2019 grouped by month, sorted by newest month first';
+ say '';
+ say ' phosta -n 10 -s lens -o count';
+ say ' show top 10 lenses used the most';
}
