adri 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2fc54b8d1ef7e4486a3d5926fc8c28633ceab6709d0a9160d026ae8497e99e65
+  data.tar.gz: ea3895da8d463f866fe4b702f0204a31596dd0047d401fc6cdcf2ff4321d676d
+SHA512:
+  metadata.gz: 5433f1bafa362f9d04e5c1c6401195941c82ba08aa86ce8f597b23459b58889311ca65e827ad5ebce9c018dea393d1a89274e840adac4926abe41c99ad7756bd
+  data.tar.gz: e9b46b82b46126ba281fd895154093bb339f9c3fb0bcc928acd888251e9ceb87323bd01f483432a8177e78c0dbd11beaa6c245dc828c512b37a96fb5f212d884

data/LICENSE.txt

@@ -0,0 +1,20 @@
+The MIT License
+
+Copyright (c) 2018 Angelos Orfanakos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,166 @@
+# adri
+
+adri organizes JPEG/TIFF photographs according to their EXIF date and location
+data into a custom directory structure.
+
+In other words, it turns this:
+
+```sh
+$ ls -1 photos/*.jpg
+IMG100001.jpg
+IMG100002.jpg
+IMG100003.jpg
+```
+
+To this:
+
+```sh
+$ tree photos/2018/
+photos/2018/
+└── 10/
+    └── 14/
+        └── London
+            ├── IMG100001.jpg
+            ├── IMG100002.jpg
+            └── IMG100003.jpg
+```
+
+## Installation
+
+Install the necessary packages. For Debian/Ubuntu, issue:
+
+```sh
+sudo apt install ruby-full git build-essential libexif-dev
+```
+
+Install adri:
+
+```sh
+sudo gem install adri
+```
+
+## Configuration
+
+adri converts the GPS coordinates (latitude and longitude) recorded in a
+photograph's EXIF headers to a location name using the [Google Maps API][].
+
+To use it, you need a free [API key][] with the Geocoding API enabled.
+
+You can then set the API key in a `GOOGLE_API_KEY` environment variable in your
+shell's configuration file. For Bash, issue:
+
+```sh
+$ cat >>.~/.bashrc
+export GOOGLE_API_KEY=yourapikeyhere
+^D
+```
+
+Note: `^D` stands for `Ctrl-D`
+
+You can also pass the API key as a command line option with `--api-key`. This
+overrides the environment variable.
+
+## Use
+
+To get the help text, issue:
+
+```sh
+$ adri -h
+usage: adri [options] <path>...
+    -p, --prefix       Place everything under this path (default: photo parent directory)
+    -f, --path-format  Format path with strftime and %{location} (default: %Y/%m/%d/%{location})
+    --api-key          Google Maps API key (default: $GOOGLE_API_KEY)
+    --run              Perform changes instead of a dry run
+    -q, --quiet        Do not print operations
+    --version          Print program version
+    -h, --help         Print help text
+```
+
+**By default, adri runs in dry run mode.** This means it simply prints out what
+it would do, without actually doing it:
+
+```sh
+$ pwd
+/home/agorf/work/adri/
+$ ls -1 photos/*.jpg
+IMG100001.jpg
+IMG100002.jpg
+IMG100003.jpg
+$ adri photos/*.jpg
+/home/agorf/work/adri/photos/IMG100001.jpg -> /home/agorf/work/adri/photos/2018/10/14/London/IMG100001.jpg (DRY RUN)
+/home/agorf/work/adri/photos/IMG100002.jpg -> /home/agorf/work/adri/photos/2018/10/14/London/IMG100002.jpg (DRY RUN)
+/home/agorf/work/adri/photos/IMG100003.jpg -> /home/agorf/work/adri/photos/2018/10/14/London/IMG100003.jpg (DRY RUN)
+$ ls -1 photos/
+IMG100001.jpg
+IMG100002.jpg
+IMG100003.jpg
+```
+
+To apply the changes, use the `--run` option:
+
+```sh
+$ adri --run photos/*.jpg
+/home/agorf/work/adri/photos/IMG100001.jpg -> /home/agorf/work/adri/photos/2018/10/14/London/IMG100001.jpg
+/home/agorf/work/adri/photos/IMG100002.jpg -> /home/agorf/work/adri/photos/2018/10/14/London/IMG100002.jpg
+/home/agorf/work/adri/photos/IMG100003.jpg -> /home/agorf/work/adri/photos/2018/10/14/London/IMG100003.jpg
+$ tree photos/
+photos/
+└── 2018/
+    └── 10/
+        └── 14/
+            └── London/
+                ├── IMG100001.jpg
+                ├── IMG100002.jpg
+                └── IMG100003.jpg
+```
+
+To place everything under a path other than the parent directory of each
+photograph, use the `--prefix` option:
+
+```sh
+$ adri --prefix . photos/*.jpg
+/home/agorf/work/adri/photos/IMG100001.jpg -> /home/agorf/work/adri/2018/10/14/London/IMG100001.jpg (DRY RUN)
+/home/agorf/work/adri/photos/IMG100002.jpg -> /home/agorf/work/adri/2018/10/14/London/IMG100002.jpg (DRY RUN)
+/home/agorf/work/adri/photos/IMG100003.jpg -> /home/agorf/work/adri/2018/10/14/London/IMG100003.jpg (DRY RUN)
+```
+
+The default path format is year/month/day/location. It is possible to specify a
+custom one with the `--path-format` option:
+
+```sh
+$ adri --path-format '%{location}/%b %Y/%d' photos/*.jpg
+/home/agorf/work/adri/photos/IMG100001.jpg -> /home/agorf/work/adri/photos/London/Oct 2018/14/IMG100001.jpg (DRY RUN)
+/home/agorf/work/adri/photos/IMG100002.jpg -> /home/agorf/work/adri/photos/London/Oct 2018/14/IMG100002.jpg (DRY RUN)
+/home/agorf/work/adri/photos/IMG100003.jpg -> /home/agorf/work/adri/photos/London/Oct 2018/14/IMG100003.jpg (DRY RUN)
+```
+
+The date is formatted according to [strftime(3)][strftime].
+
+It's also possible to process many photos at once by passing space-separated
+file names and directories (in which case adri will [recurse][]):
+
+```sh
+$ adri photos/IMG100001.jpg photos/IMG100002.jpg photos/IMG100003.jpg
+/home/agorf/work/adri/photos/IMG100001.jpg -> /home/agorf/work/adri/photos/2018/10/14/London/IMG100001.jpg (DRY RUN)
+/home/agorf/work/adri/photos/IMG100002.jpg -> /home/agorf/work/adri/photos/2018/10/14/London/IMG100002.jpg (DRY RUN)
+/home/agorf/work/adri/photos/IMG100003.jpg -> /home/agorf/work/adri/photos/2018/10/14/London/IMG100003.jpg (DRY RUN)
+$ adri photos/
+/home/agorf/work/adri/photos/IMG100001.jpg -> /home/agorf/work/adri/photos/2018/10/14/London/IMG100001.jpg (DRY RUN)
+/home/agorf/work/adri/photos/IMG100002.jpg -> /home/agorf/work/adri/photos/2018/10/14/London/IMG100002.jpg (DRY RUN)
+/home/agorf/work/adri/photos/IMG100003.jpg -> /home/agorf/work/adri/photos/2018/10/14/London/IMG100003.jpg (DRY RUN)
+```
+
+## License
+
+[MIT][]
+
+## Author
+
+[Angelos Orfanakos](https://agorf.gr/contact/)
+
+[Bundler]: https://bundler.io/
+[Google Maps API]: https://developers.google.com/maps/documentation/javascript/examples/geocoding-reverse
+[API key]: https://cloud.google.com/maps-platform/#get-started
+[MIT]: https://github.com/agorf/adri/blob/master/LICENSE.txt
+[recurse]: https://softwareengineering.stackexchange.com/a/184600/316578
+[strftime]: http://man7.org/linux/man-pages/man3/strftime.3.html

data/bin/adri

@@ -0,0 +1,306 @@
+#!/usr/bin/env ruby
+
+require 'fileutils'
+require 'time'
+
+begin
+  require 'dotenv/load'
+rescue LoadError
+end
+
+require 'exif'
+require 'geocoder'
+require 'slop'
+
+module Adri
+  DEFAULT_PATH_FORMAT = '%Y/%m/%d/%{location}'.freeze
+  EXTENSIONS = %w[jpg jpeg JPG JPEG tif tiff TIF TIFF].freeze
+  GEOCODE_MAX_DELAY = 60 # Seconds
+  LOCATION_CACHE_SCALE = 2
+  VERSION = '0.0.1'.freeze
+
+  class Photo
+    class << self
+      attr_accessor :location_cache
+    end
+
+    self.location_cache = Hash.new(false)
+
+    attr_reader(
+      :source_path,
+      :prefix,
+      :path_format,
+      :verbose,
+      :dry_run
+    )
+
+    def initialize(path, options)
+      @source_path = File.absolute_path(path)
+      @path_format = options[:path_format].gsub('/', File::SEPARATOR)
+      @verbose = !options[:quiet]
+      @dry_run = !options[:run]
+
+      @prefix =
+        if options[:prefix].to_s.strip.empty?
+          File.dirname(@source_path)
+        else
+          File.absolute_path(options[:prefix])
+        end
+    end
+
+    def date_time
+      return @date_time if @date_time
+
+      if exif&.date_time && exif.date_time != '0000:00:00 00:00:00'
+        @date_time =
+          Time.strptime(exif.date_time.sub(' 24:', ' 00:'), '%Y:%m:%d %H:%M:%S')
+      end
+    end
+
+    def latitude
+      return @latitude if @latitude
+
+      if exif&.gps_latitude
+        @latitude = geo_float(exif.gps_latitude)
+      end
+    end
+
+    def longitude
+      return @longitude if @longitude
+
+      if exif&.gps_longitude
+        @longitude = geo_float(exif.gps_longitude)
+      end
+    end
+
+    def location
+      return @location if defined?(@location)
+
+      @location = read_location_from_cache
+
+      return @location if @location != false
+
+      @location = location_from_latlng
+
+      write_location_to_cache
+
+      @location
+    end
+
+    def destination_path
+      return @destination_path if @destination_path
+
+      path = date_time.strftime(path_format)
+
+      if location_in_path_format?
+        path = sprintf(path, location: location)
+      end
+
+      @destination_path ||= File.join(
+        prefix,
+        path,
+        File.basename(source_path)
+      )
+    end
+
+    def move
+      return if skip_move?
+
+      if verbose
+        puts sprintf(
+          '%s -> %s%s',
+          source_path,
+          destination_path,
+          dry_run ? ' (DRY RUN)' : ''
+        )
+      end
+
+      return if dry_run
+
+      FileUtils.mkdir_p(File.dirname(destination_path))
+      FileUtils.mv(source_path, destination_path)
+    end
+
+    private def exif
+      begin
+        @exif ||= Exif::Data.new(File.open(source_path))
+      rescue Exif::NotReadable
+      end
+    end
+
+    private def location_in_path_format?
+      path_format['%{location}']
+    end
+
+    private def latlng
+      @latlng ||= [latitude, longitude].compact
+    end
+
+    private def skip_move?
+      if !File.exist?(source_path)
+        puts "Missing file #{source_path}" if verbose
+        return true
+      end
+
+      if date_time.nil?
+        puts "No datetime data #{source_path}" if verbose
+        return true
+      end
+
+      if location_in_path_format?
+        if latlng.empty?
+          puts "No location data #{source_path}" if verbose
+          return true
+        end
+
+        if location.nil? # Geocoding failed
+          puts "Unknown location #{source_path}" if verbose
+          return true
+        end
+      end
+
+      if File.exist?(destination_path)
+        puts "Existing file #{destination_path}" if verbose
+        return true
+      end
+
+      false
+    end
+
+    private def location_from_latlng
+      current_delay = 0.1 # 100 ms
+
+      begin
+        geocode_results = Geocoder.search(latlng)
+      rescue Geocoder::OverQueryLimitError
+        puts 'Got OverQueryLimitError' if verbose
+
+        if current_delay > GEOCODE_MAX_DELAY
+          puts "Exceeded max delay of #{GEOCODE_MAX_DELAY} seconds" if verbose
+          return
+        end
+
+        puts "Waiting #{current_delay} seconds before retrying..." if verbose
+        sleep(current_delay)
+        current_delay *= 2 # Exponential backoff
+
+        retry
+      end
+
+      geocode_results.map(&:city).compact.uniq.first
+    end
+
+    private def location_cache_key
+      @location_cache_key ||= [
+        latitude.truncate(LOCATION_CACHE_SCALE).to_s,
+        longitude.truncate(LOCATION_CACHE_SCALE).to_s
+      ]
+    end
+
+    private def write_location_to_cache
+      self.class.location_cache[location_cache_key] = location
+    end
+
+    private def read_location_from_cache
+      self.class.location_cache[location_cache_key]
+    end
+
+    private def geo_float(value)
+      degrees, minutes, seconds = value
+      degrees + minutes / 60.0 + seconds / 3600.0
+    end
+  end
+
+  def self.parse_args
+    Slop.parse do |o|
+      o.banner = "usage: #{$PROGRAM_NAME} [options] <path>..."
+
+      o.string(
+        '-p',
+        '--prefix',
+        'Place everything under this path (default: photo parent directory)'
+      )
+
+      o.string(
+        '-f',
+        '--path-format',
+        'Format path with strftime and %{location} (default: ' \
+          "#{DEFAULT_PATH_FORMAT})",
+        default: DEFAULT_PATH_FORMAT
+      )
+
+      o.string(
+        '--api-key',
+        'Google Maps API key (default: $GOOGLE_API_KEY)',
+        default: ENV['GOOGLE_API_KEY']
+      )
+
+      o.bool('--run', 'Perform changes instead of a dry run')
+
+      o.bool('-q', '--quiet', 'Do not print operations')
+
+      o.on('--version', 'Print program version') do
+        puts [$PROGRAM_NAME, VERSION].join(' ')
+        exit
+      end
+
+      o.on('-h', '--help', 'Print help text') do
+        puts o
+        exit
+      end
+    end
+  end
+
+  def self.expand_paths(paths, verbose)
+    glob_pattern = File.join('**', "*.{#{EXTENSIONS.join(',')}}")
+
+    Enumerator.new do |y|
+      paths.each do |path|
+        file_paths =
+          if FileTest.directory?(path)
+            Dir.glob(File.join(path, glob_pattern)).sort
+          elsif !File.exist?(path)
+            puts "Missing #{path}" if verbose
+          elsif !FileTest.file?(path) || FileTest.symlink?(path)
+            puts "Not a file #{path}" if verbose
+          elsif !EXTENSIONS.include?(File.extname(path).delete('.'))
+            if verbose
+              puts "File extension not one of: #{EXTENSIONS.join(', ')}"
+            end
+          else
+            [path]
+          end || []
+
+        file_paths.each do |file_path|
+          y << file_path
+        end
+      end
+    end
+  end
+end
+
+opts = Adri.parse_args
+args = opts.arguments
+
+if args.empty?
+  puts opts
+  exit
+end
+
+options = opts.to_h
+
+if options[:path_format]['%{location}'] && options[:api_key].to_s.strip.empty?
+  puts 'Please specify a Google Maps API key or remove %{location} from path ' \
+    'format'
+  exit 1
+end
+
+Geocoder.configure(
+  always_raise: :all,
+  lookup: :google,
+  api_key: options[:api_key]
+)
+
+Adri.expand_paths(args, !options[:quiet]).each do |path|
+  Adri::Photo.new(path, options).move
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: adri
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Angelos Orfanakos
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-12-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: exif
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+- !ruby/object:Gem::Dependency
+  name: geocoder
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+- !ruby/object:Gem::Dependency
+  name: slop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.6.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.6.2
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+description: 
+email: me@agorf.gr
+executables:
+- adri
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- bin/adri
+homepage: https://github.com/agorf/adri
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Organize photos by date and location in a directory structure
+test_files: []