commit e4cb3843f21e958adca73f52a760e83ed110e1be
parent 0310ecd683a6586ac63f67fdc5802ad049bc61d3
Author: René Wagner <rwa@clttr.info>
Date: Tue, 11 Apr 2023 22:09:11 +0200
Merge branch 'manpage'
Diffstat:
7 files changed, 288 insertions(+), 26 deletions(-)
diff --git a/Makefile b/Makefile
@@ -0,0 +1,44 @@
+VERSION=1.1
+PREFIX?=/usr/local
+BINDIR?=$(PREFIX)/bin
+MANDIR?=$(PREFIX)/share/man
+DOCDIR?=$(PREFIX)/share/doc
+.DEFAULT_GOAL=all
+
+phosta:
+
+phosta.1: phosta.1.scd
+ scdoc < $< > $@
+
+phosta-alias.5: phosta-alias.5.scd
+ scdoc < $< > $@
+
+phosta-examples.7: phosta-examples.7.scd
+ scdoc < $< > $@
+
+phosta-faq.7: phosta-faq.7.scd
+ scdoc < $< > $@
+
+all: phosta phosta.1 phosta-alias.5 phosta-examples.7 phosta-faq.7
+
+clean:
+ rm -rf phosta.1 phosta-alias.5 phosta-examples.7 phosta-faq.7
+
+install: all
+ mkdir -p $(DESTDIR)/$(BINDIR) $(DESTDIR)/$(MANDIR)/man1 $(DESTDIR)/$(MANDIR)/man5 $(DESTDIR)/$(MANDIR)/man7 $(DESTDIR)/$(DOCDIR)/phosta/
+ install -m755 phosta $(DESTDIR)/$(BINDIR)/phosta
+ install -m644 phosta.1 $(DESTDIR)/$(MANDIR)/man1/phosta.1
+ install -m644 phosta-alias.5 $(DESTDIR)/$(MANDIR)/man5/phosta-alias.5
+ install -m644 phosta-examples.7 $(DESTDIR)/$(MANDIR)/man7/phosta-examples.7
+ install -m644 phosta-faq.7 $(DESTDIR)/$(MANDIR)/man7/phosta-faq.7
+ install -m644 LICENSE $(DESTDIR)/$(DOCDIR)/phosta/LICENSE
+
+uninstall:
+ rm -f $(DESTDIR)/$(BINDIR)/phosta
+ rm -f $(DESTDIR)/$(MANDIR)/man1/phosta.1
+ rm -f $(DESTDIR)/$(MANDIR)/man5/phosta-alias.5
+ rm -f $(DESTDIR)/$(MANDIR)/man7/phosta-examples.7
+ rm -f $(DESTDIR)/$(MANDIR)/man7/phosta-faq.7
+
+check: phosta phosta.1 phosta-alias.5 phosta-examples.7 phosta-faq.7
+ @find test -perm -111 -exec '{}' \;
diff --git a/README.md b/README.md
@@ -2,7 +2,9 @@
This project is a small statistic generator for the terminal which accumulates data about your photographical habits.
-It is mainly a selfcontained [SQlite](https://sqlite.org) database that stores the data which is extracted from the exif data of your images using [exiftool](https://exiftool.org/) and provides some methods to query the gathered data and gain some statistical insight.
+It is mainly a selfcontained [SQlite](https://sqlite.org) database that stores the data which is extracted from the EXIF data of your images using [exiftool](https://exiftool.org/) and provides some methods to query the gathered data and gain some statistical insight.
+
+For extensive usage information see `man phosta`.
## features
- loading of EXIF data from media files to a self-contained database
@@ -83,17 +85,21 @@ A total of **5090 images** matched your criteria.
'-----------------------------+---------------+-------+---------'
```
-## requirements
-The famous `exiftool` needs to be installed on your system.
-
-Simply clone the repo or manually download the scripts from https://git.sr.ht/~rwa/photo-stats/blob/master/phosta and put the file into a folder that is included in your `$PATH`.
+## Installation
+Clone the repo, then run
+```
+$ make
+$ sudo make install
+```
-For ArchLinux, `phosta` is available as an AUR package that takes care of the dependencies.
+For ArchLinux, `phosta` is available as an [AUR package](https://aur.archlinux.org/packages/phosta) that takes care of the dependencies.
-To run the script, open a shell and invoke `perl phosta`, on most systems it should be sufficient to just invoke `phosta` (after you granted execute-permissions to the script).
+To run the script, open a shell and invoke `phosta`.
#### prerequisites for running the pure scripts
+- exiftool
+- SQLite 3
- Perl 5.30 (or newer)
Additionally the following perl modules need to be installed:
@@ -103,6 +109,7 @@ Additionally the following perl modules need to be installed:
- File::Spec::Functions
- Perl::DBD::SQLite
- Perl::DBI
+- Perl::Modern
- Text::SimpleTable::AutoWidth
- Term::AnsiColor
- Scalar:Util
diff --git a/phosta b/phosta
@@ -1,5 +1,5 @@
#!/usr/bin/perl
-# Copyright(c) René Wagner 2019-2020
+# Copyright(c) René Wagner 2019-2023
# https://src.clttr.info/rwa/photo-stats
# published under BSD 3-Clause License
@@ -19,14 +19,14 @@ use Data::Dumper;
$Getopt::Std::STANDARD_HELP_VERSION = 'true';
my $VERSION = '1.2';
-my $PROGRAM = 'Photo Stats';
+my $PROGRAM = 'phosta';
my $configfile = catfile(File::HomeDir->my_home, '.phosta.conf');
my $aliasfile = catfile(File::HomeDir->my_home, '.phosta.alias');
# read commandline switches
our $opt_E='jpg,jpeg';
-our $opt_D=getcwd . "/photo_stats.db";
+our $opt_D= catfile(File::HomeDir->my_home, '.phosta.db');
our $opt_p='';
our $opt_t=undef;
our $opt_c=0;
@@ -40,13 +40,19 @@ our $opt_f=undef;
our $opt_e=0;
our $opt_W=80;
our $opt_T='auto';
+our $opt_h=undef;
getconfig();
-getopts('vcrp:n:g:s:t:D:E:o:f:eW:T:') or die "Invalid parameters provided! See 'phosta --help' for more details.";
+getopts('hvcrp:n:g:s:t:D:E:o:f:eW:T:') or die "Invalid parameters provided! See 'phosta --help' for more details.";
validate() or die "Invalid parameters provided! See 'phosta --help' for more details.";
my $dsn = "DBI:SQLite:dbname=$opt_D";
+if ($opt_h) {
+ main::HELP_MESSAGE();
+ exit 0;
+}
+
if ($opt_c) { unlink $opt_D; }
if ( !-e $opt_D ) { create_db($opt_D) or die 'database could not be created'; }
@@ -422,9 +428,8 @@ sub result_to_table
sub main::VERSION_MESSAGE()
{
say $PROGRAM . ' - version ' . $VERSION;
- say 'published under BSD 3 - Clause License';
- say 'Copyright(c) 2019-2020 René Wagner';
say 'https://git.sr.ht/~rwa/photo-stats';
+ say 'Copyright(c) 2019-2023 René Wagner - published under BSD 3 - Clause License';
}
sub main::HELP_MESSAGE
@@ -437,7 +442,7 @@ sub main::HELP_MESSAGE
say 'Options with upper-case letters are automatically saved in the user config and can be omitted if no change is required.';
say '';
say 'generic options:';
- say ' -D <file> : path and name of the db file to use, defaults to <workingdir>/photo_stats.db';
+ say ' -D <file> : path and name of the db file to use, defaults to ~/photo_stats.db';
say ' -c : clear the database';
say ' -v : be verbose - print some debug output';
say ' --help : show this help';
@@ -469,16 +474,5 @@ sub main::HELP_MESSAGE
say ' -T <value> : show results as always as a table (on) or not (off) or auto (chart when single field is selected), default is auto';
say ' allowed values: auto, on, off';
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 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';
- say '';
- say ' phosta -s model -f maker!=ricoh';
- say ' show camera models where the maker field does not contain the term "ricoh"';
+ say 'For further information see the man pages phosta(1), phosta-alias(5) and phosta-examples(7).';
}
diff --git a/phosta-alias.5.scd b/phosta-alias.5.scd
@@ -0,0 +1,30 @@
+phosta-alias(5) "phosta" "Alias File Format Definition"
+
+# NAME
+phosta-alias - configuration of word replacement for *phosta*(1)
+
+# SYNOPSIS
+*phosta* allows to configure automatic word replacement during the data import.
+This allows to sanitize and unify ambigous naming used by different image processing tools.
+
+This is configured via the user-defined config file _~/.phosta.alias_.
+
+The replacement takes place when importing the EXIF data in our database. Every occurence of *old string* will be replaced by *new_string*. The search is *case-sensitive*.
+
+# SYNTAX
+The file _~/.phosta.alias_ is a plain text file. It should hold an alias definition per line.
+An alias definition consists of the old string, which should be replaced, and the new string which should be put in instead, separat by atleast one tabstop.
+
+```
+Old company new company
+lensname real lensname
+```
+
+# SEE ALSO
+
+*phosta*(1), *phosta-examples*(7), *phosta-faq*(7)
+
+# AUTHORS
+
+Maintained by René Wagner <rwa@clttr.info>.++
+Project repo can be found at https://git.sr.ht/~rwa/photo-stats
diff --git a/phosta-examples.7.scd b/phosta-examples.7.scd
@@ -0,0 +1,40 @@
+phosta-examples(7) "phosta" "phosta Examples"
+
+# NAME
+phosta-examples - collection of example calls with params for *phosta*(1)
+
+# SYNOPSIS
+*phosta* allows to configure automatic word replacement during the import of data.
+This allows to sanitize and unify ambigous naming used by different image processing tools.
+
+# EXAMPLES
+## GATHER DATA
+- load data of files with the extensions jpg, jpeg and tiff in folder _~/Pictures_ to the database located in _~/Documents/stats.db_
+```
+phosta -E jpg,jpeg,tiff -D ~/Documents/stats.db -p ~/Pictures
+```
+
+## QUERY DATA
+- show number of pictures taken with a specific camera body in 2019 grouped by month, sorted by newest month first
+```
+phosta -s model -g month -t 20190101-20121231 -o month,count
+```
+
+- show top 10 lenses used the most
+```
+phosta -n 10 -s lens -o count
+```
+
+- show camera models where the maker field does not contain the term "ricoh"
+```
+phosta -s model -f maker!=ricoh
+```
+
+# SEE ALSO
+
+*phosta*(1), *phosta-alias*(5), *phosta-faq*(7)
+
+# AUTHORS
+
+Maintained by René Wagner <rwa@clttr.info>.++
+Project repo can be found at https://git.sr.ht/~rwa/photo-stats
diff --git a/phosta-faq.7.scd b/phosta-faq.7.scd
@@ -0,0 +1,23 @@
+phosta-faq(7) "phosta" "Frequently Asked Questions"
+
+# NAME
+phosta-faq - frequently asked questions about the usage of *phosta*(1)
+
+# FAQ
+*I want to use a filter with whitespaces, how can i do that?*
+ You need to surround the parameter value with quotation marks, e.g. phosta -f "maker=best company".
+
+*I have my images on a network share, how can i include them into the stats?*
+ You should mount the share and use is like a local directory.
+
+*Can i add different folders to the statistics?*
+ Omit the -c param when populating the database to avoid cleaning up old values. The tool will take care that no duplicates are added. The duplicate detection is based on file path and name.
+
+# SEE ALSO
+
+*phosta*(1), *phosta-alias*(5), *phosta-examples*(7)
+
+# AUTHORS
+
+Maintained by René Wagner <rwa@clttr.info>.
+Project repo can be found at https://git.sr.ht/~rwa/photo-stats
diff --git a/phosta.1.scd b/phosta.1.scd
@@ -0,0 +1,124 @@
+phosta(1) "phosta" "phosta Documenation"
+
+# NAME
+phosta - photo statistic processor for your terminal
+
+# SYNOPSIS
+*phosta* [*-v*] [*-D* _<file>_] ...
+
+*phosta* is a small statistics processor for your terminal.
+It extracts EXIF data of your images and stores it in an internal database. This allows you to query many different aggregations (like "which lens did i use most recently?") without the need to read over all your images again and again. You don't even need to have access to your images when digging through the stats.
+
+# USAGE
+
+You could use as many different databases as you'd like to, whatever suits your needs (maybe split private and commercial data). Use the *-D* param to specify on which database file you want to operate.
+
+## POPULATE DATABASE
+The first step is to populate your database with the EXIF data extracted from your images. You can import the data of all your images at once or doing incremental imports. Each import will update existing data and add new files based on file path and name.
+
+Different image processing tools may use a different naming for one and the same body or lens. To sanitize your data, *phosta* supports a simple word replacement mechanism during data import, see *phosta-alias*(5) for more information.
+
+## QUERY DATA
+*Selecting Data*++
+What data you are going to see is specified by the *-s* param. urrently the following fields are collected and stored in the database:
+
+- file
+- maker
+- model
+- lens maker
+- lens
+- aperture
+- exposuretime
+- iso
+- focallength
+- focallength35mm
+
+*Grouping*++
+Grouping can be applied based on various pre-defined time ranges.
+
+*Filters*++
+Filtering the raw data allows you to narrow down the result set. You can filter by time range using the *-t* param or apply an arbitrary text filter with the *-f* param.
+
+*Limits*++
+You can limit the output to the top results using the *-n* param. The tool will tell you how many lines are skipped due to this param.
+
+Additionally there's the *-e* switch to skip the "empty" result. The empty result occur especially on some EXIF fields like exposure time, aperture and the like where sometimes invalid values are stored in the images.
+
+*Ordering*++
+By default the ordering starts with the results with the most count and descends. You can enforce an arbitrary ordering by specifying the fields you want to order by with the *-o* param.
+
+Additionally there's the *-r* flag to invert the sort order, which means order in ascending manner.
+
+You can find a set of sample querys in *phosta-examples*(7).
+
+# OPTIONS
+Options in CAPITAL LETTERS (like *-D*) will automatically be persisted in the user's config file located at _~/.phosta.conf_.
+
+## GENERIC OPTIONS
+ *-D* <file>
+ Path and name of the database file to use, either for populating a new database or defining which database should be queried.++
+ The last database used is automatically persisted to the user config so you may skip the parameter for the next query.++
+ default: _~/photo_stats.db_
+
+ *-c*
+ Remove all data from the working database (see *-D*). Use with caution, there will be no additional warning!
+
+## DATA EXTRACTION OPTIONS
+ *-p* <folder>
+ Read the media files that match the extension filter (see *-E*) in the given folder and all subfolders, extract the EXIF data Populate database with the EXIF data of the media files in the specified folder
+
+ *-E* <ext>
+ List of comma separated extensions used for scanning image files.++
+Only media files which match (case-insensitive!) the given extensions are added to the database.++
+Default: _jpg,jpeg_
+
+## QUERY OPTIONS
+ *-e*
+ Skip lines with empty selected or grouping fields.
+
+ *-f* <expr>
+ Filter images based on the given expression, multiple expression can be given as a comma-separated list.++
+This works as a case-insensitive search, multiple expressions need to match all (AND logic), use _field=value_ for CONTAINS and _field!=value_ for NOT CONTAINS++
+Allowed values: _file_, _maker_, _model_, _lensmake_, _lens_, _aperture_, _exposuretime_, _iso_, _focallength_, _focallength35mm_
+
+ *-g* <period>
+ Group result set by a time period.++
+Default: total (which means no grouping by period)++
+Allowed values: _year_, _month_, _week_, _hour_
+
+ *-n* <number>
+ Limit the resultset to <number> of lines.
+
+ *-o* <fields>
+ Sort the output by the given fields (sequence matters!) in descending order.++
+Allowed values: any comma separated combination of the values of *-g* and *-s* param and _count_
+
+ *-r*
+ Sort in reverse (ascending) order, default is descending order
+
+ *-s* <fields>
+ Specify the information you want to include in the output, multiple fields should be listed comma-separated (without withspaces or enclosed in "")++
+Default: none (just show number of images)++
+Allowed values: _file_, _maker_, _model_, _lensmake_, _lens_, _aperture_, _exposuretime_, _iso_, _focallength_, _focallength35mm_
+
+ *-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 the first or the later value, e.g. _-YYYYMMDD_.
+
+ *-T* <value>
+ Show results as always as a table (on) or not (off) or auto (display as chart only when single field is selected).++
+Default: auto++
+Allowed values: _auto_, _on_, _off_
+
+ *-W* <number>
+ Define maximum width of the output in characters, _-1_ deletes the current setting.++
+Default: 80 (a minimum of 50 is required for meaningful output)
+
+# SEE ALSO
+
+*phosta_alias*(5), *phosta-examples*(7), *phosta-faq*(7)
+
+# AUTHOR
+
+Maintained by René Wagner <rwa@clttr.info>.++
+Project repo can be found at https://git.sr.ht/~rwa/photo-stats
