Browse Source

prepare 1.0 release

master 1.0
René Wagner 10 months ago
parent
commit
ad0939f50e
  1. 9
      CHANGELOG.md
  2. 107
      README.md
  3. 15
      phosta.pl

9
CHANGELOG.md

@ -0,0 +1,9 @@
# Changelog
## 1.0 (31.08.2020)
initial release with the following features:
- extract EXIF data from media files and store it in the database
- allow querying of statistic data
- filter statistics by arbitrary text
- filter statistics based on time of images
- group by different time ranges
- order output by user-defined field

107
README.md

@ -2,36 +2,12 @@
[![builds.sr.ht status](https://builds.sr.ht/~rwa/photo-stats.svg)](https://builds.sr.ht/~rwa/photo-stats?)
This project is a small statistic generator for the terminal which accumulates about your photographical habits.
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.
**Additional information can be found on the [wiki page](https://man.sr.ht/~rwa/photo-workflow/photo-stats.md).**
## requirements
The famous `exiftool` needs to be installed on your system, no matter if you use prebuilt binarys or the bare scripts.
### using binary (recommended)
There are prebuilt binarys (currently only x86\_64 for linux and Haiku) and packages for Arch Linux and derivatives available for [every ref](https://git.sr.ht/~rwa/photo-stats/refs).
### using bare scripts
Simply clone the repo or manually download the scripts from https://git.sr.ht/~rwa/photo-stats/
To run the script, open a shell and invoke `perl phosta.pl`, on most systems it should be sufficient to just invoke `phosta.pl` (after you granted execute-permissions to the script).
#### prerequisites for running the pure scripts
- Perl 5.30 (or newer)
Additionally the following perl modules need to be installed:
- Cwd
- File::HomeDir
- File::Spec::Functions
- Perl::DBD::SQLite
- 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
@ -53,6 +29,13 @@ Additionally the following perl modules need to be installed:
- custom sorting of output by arbitrary fields
- output results in a table view to your terminal
## usage
Before you can query some stats, the EXIF data has to be extracted from your media files and written to the database.
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.
### example output
```
Querying database ~/photos.db with 82 entries...
@ -74,60 +57,26 @@ Querying database ~/photos.db with 82 entries...
'-----------------+-------+---------'
```
## usage
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.
## requirements
The famous `exiftool` needs to be installed on your system, no matter if you use prebuilt binarys or the bare scripts.
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.
### using binary (recommended)
There are prebuilt binarys (currently only x86\_64 for linux and Haiku) and packages for Arch Linux and derivatives available for [every ref](https://git.sr.ht/~rwa/photo-stats/refs).
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 <period> : group by a time period, defaults to total (which means no grouping by period)
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
-f <expr> : filter images based on the given expression, multiple expression can be given comma-separated
this works as a case-insensitive CONTAINS search, multiple expressions need to match all (AND logic)
use "field=value" for CONTAINS and "field!=value" for NOT CONTAINS, value must not include whitespaces
allowed fields: file, maker, model, lensmake, lens, aperture, exposuretime, iso, focallength, focallength35mm
-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
-e : skip lines with empty selected or grouping fields
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 in 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
phosta -s model -f maker!=ricoh
show camera models where the maker field does not contain the term "ricoh"
```
### using bare scripts
Simply clone the repo or manually download the scripts from https://git.sr.ht/~rwa/photo-stats/
To run the script, open a shell and invoke `perl phosta.pl`, on most systems it should be sufficient to just invoke `phosta.pl` (after you granted execute-permissions to the script).
#### prerequisites for running the pure scripts
- Perl 5.30 (or newer)
Additionally the following perl modules need to be installed:
- Cwd
- File::HomeDir
- File::Spec::Functions
- Perl::DBD::SQLite
- Perl::DBI
- Text::SimpleTable::AutoWidth

15
phosta.pl

@ -17,7 +17,7 @@ use File::HomeDir;
$Getopt::Std::STANDARD_HELP_VERSION = 'true';
my $VERSION = '0.9';
my $VERSION = '1.0';
my $PROGRAM = 'Photo Stats';
my $configfile = catfile(File::HomeDir->my_home, '.phosta.conf');
@ -354,17 +354,16 @@ sub main::HELP_MESSAGE
say '';
say 'generic options:';
say ' -D <file> : path and name of the db file to use, defaults to <workingdir>/photo_stats.db';
say ' This option is automatically saved in the user conf, you can omit this option if you always use the same db';
say ' This option is automatically saved in the user config and be can omitted when using same db again.';
say ' -c : clear the database';
say ' -v : be verbose - print some debug output';
say ' --help : show this help';
say '';
say 'data gathering:';
say ' -p <folder> : populate database from the files in the specified folder';
say ' Media files in the given folder and every subfolder are scanned, EXIF data extracted and pulled into the database';
say ' -p <folder> : populate database with the EXIF data of the media files in the specified folder';
say ' -E <ext> : list of comma separated extensions used for scanning image files, defaults to jpg,jpeg';
say ' only media files which match (case-insensitive!) the given extensions are added to the database';
say ' This option is automatically saved to the user conf';
say ' This option is automatically saved to the user config.';
say '';
say 'stats querying:';
say ' -g <period> : group by a time period, defaults to total (which means no grouping by period)';
@ -375,13 +374,13 @@ sub main::HELP_MESSAGE
say ' -t <range> : only take images into account which have been taken in the given timerange';
say ' <range> must be specified as \'YYYYMMDD-YYYYMMDD\', you can omit the first or the later value';
say ' -f <expr> : filter images based on the given expression, multiple expression can be given comma-separated';
say ' this works as a case-insensitive CONTAINS search, multiple expressions need to match all (AND logic)';
say ' use "field=value" for CONTAINS and "field!=value" for NOT CONTAINS, value must not include whitespaces';
say ' this works as a case-insensitive search, multiple expressions need to match all (AND logic)';
say ' use "field=value" for CONTAINS and "field!=value" for NOT CONTAINS';
say ' allowed fields: file, maker, model, lensmake, lens, aperture, exposuretime, iso, focallength, focallength35mm';
say ' -n <number> : limit the resultset to <number> of lines';
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 ' -r : sort in reverse (ascending) order, default is descending order';
say ' -e : skip lines with empty selected or grouping fields';
say '';
say 'examples:';

Loading…
Cancel
Save