exiftool-vendored.pl 12.80.0 → 12.84.0

package/bin/lib/Image/ExifTool/Geolocation.pm

@@ -1,20 +1,30 @@
 #------------------------------------------------------------------------------
 # File:         Geolocation.pm
 #
-# Description:  Look up geolocation information based on a GPS position
+# Description:  Determine geolocation from GPS and visa-versa
 #
 # Revisions:    2024-03-03 - P. Harvey Created
+#               2024-03-21 - PH Significant restructuring and addition of
+#                            several new features.
 #
 # References:   https://download.geonames.org/export/
 #
-# Notes:        Set $Image::ExifTool::Geolocation::geoDir to override
-#               default directory for the database file Geolocation.dat
-#               and language directory GeoLang.
+# Notes:        Set $Image::ExifTool::Geolocation::geoDir to override the
+#               default directory containing the database file Geolocation.dat
+#               and the GeoLang directory with the alternate language files.
+#               If set, this directory is 
 #
-#               Based on data from geonames.org Creative Commons databases,
-#               reformatted as follows in the Geolocation.dat file:
+#               AltNames.dat may be loaded from a different directory by
+#               specifying $Image::ExifTool::Geolocation::altDir.  This
+#               database and has entries in the same order as Geolocation.dat,
+#               and each entry is a newline-separated list of alternate names
+#               terminated by a null byte.
 #
-#   Header: 
+#               Databases are based on data from geonames.org with a
+#               Creative Commons license, reformatted as follows in the
+#               Geolocation.dat file:
+#
+#   Header:
 #       "GeolocationV.VV\tNNNN\n"  (V.VV=version, NNNN=num city entries)
 #       "# <comment>\n"
 #   NNNN City entries:
@@ -25,9 +35,10 @@
 #        5   int8u  - index of country in country list
 #        6   int8u  - 0xf0 = population E exponent (in format "N.Fe+0E"), 0x0f = population N digit
 #        7   int16u - 0xf000 = population F digit, 0x0fff = index in region list (admin1)
-#        9   int16u - 0x7fff = index in subregion (admin2), 0x8000 = high bit of time zone
+#        9   int16u - v1.02: 0x7fff = index in subregion (admin2), 0x8000 = high bit of time zone
+#        9   int16u - v1.03: index in subregion (admin2)
 #       11   int8u  - low byte of time zone index
-#       12   int8u  - 0x0f - feature code index (see below)
+#       12   int8u  - 0x3f = feature code index (see below), v1.03: 0x80 = high bit of time zone
 #       13   string - UTF8 City name, terminated by newline
 #   "\0\0\0\0\x01"
 #   Country entries:
@@ -42,11 +53,14 @@
 #   "\0\0\0\0\x04"
 #   Time zone entries:
 #       1. Time zone name, terminated by newline
+#   "\0\0\0\0\x05" (feature codes added in v1.03)
+#   Feature codes:
+#       1. Feature code, terminated by newline
 #   "\0\0\0\0\0"
 #
-# Feature Codes: (see http://www.geonames.org/export/codes.html#P for descriptions)
+# Feature Codes v1.02: (see http://www.geonames.org/export/codes.html#P for descriptions)
 #
-#       0. Other    3. PPLA2    6. PPLA5    9. PPLF    12. PPLR
+#       0. Other    3. PPLA2    6. PPLA5    9. PPLF    12. PPLR   15. PPLX
 #       1. PPL      4. PPLA3    7. PPLC    10. PPLG    13. PPLS
 #       2. PPLA     5. PPLA4    8. PPLCH   11. PPLL    14. STLMT
 #------------------------------------------------------------------------------
@@ -54,28 +68,29 @@
 package Image::ExifTool::Geolocation;
 
 use strict;
-use vars qw($VERSION $geoDir $dbInfo);
+use vars qw($VERSION $geoDir $altDir $dbInfo);
 
-$VERSION = '1.02';
+$VERSION = '1.07';  # (this is the module version number, not the database version)
 
-my $databaseVersion = '1.02';
+my $debug; # set to output processing time for testing
 
 sub ReadDatabase($);
 sub SortDatabase($);
 sub AddEntry(@);
-sub GetEntry($;$);
-sub Geolocate($;$$$$$);
+sub GetEntry($;$$);
+sub Geolocate($;$);
 
 my (@cityList, @countryList, @regionList, @subregionList, @timezoneList);
-my (%countryNum, %regionNum, %subregionNum, %timezoneNum, %langLookup);
+my (%countryNum, %regionNum, %subregionNum, %timezoneNum); # reverse lookups
+my (@sortOrder, @altNames, %langLookup, $nCity, %featureCodes);
+my ($lastArgs, %lastFound, @lastByPop, @lastByLat); # cached city matches
+my $dbVer = '1.03';
 my $sortedBy = 'Latitude';
 my $pi = 3.1415926536;
 my $earthRadius = 6371;    # earth radius in km
-
-my @featureCodes = qw(Other PPL PPLA PPLA2 PPLA3 PPLA4 PPLA5
-                      PPLC PPLCH PPLF PPLG PPLL PPLR PPLS STLMT ?);
-my $i = 0;
-my %featureCodes = map { lc($_) => $i++ } @featureCodes;
+# hard-coded feature codes for v1.02 database
+my @featureCodes = qw(Other PPL PPLA PPLA2 PPLA3 PPLA4 PPLA5 PPLC
+                      PPLCH PPLF PPLG PPLL PPLR PPLS STLMT PPLX);
 
 # get path name for database file from lib/Image/ExifTool/Geolocation.dat by default,
 # or according to $Image::ExifTool::Geolocation::directory if specified
@@ -94,12 +109,10 @@ unless (defined $geoDir and not $geoDir) {
     }
 }
 
-# set directory for language files
-my $geoLang;
-if ($geoDir and -d "$geoDir/GeoLang") {
-    $geoLang = "$geoDir/GeoLang";
-} elsif ($geoDir or not defined $geoDir) {
-    $geoLang = "$defaultDir/GeoLang";
+# set directory for language files and alternate names
+$geoDir = $defaultDir unless defined $geoDir;
+if (not defined $altDir and $geoDir and -e "$geoDir/AltNames.dat") {
+    $altDir = $geoDir;
 }
 
 # add user-defined entries to the database
@@ -115,7 +128,7 @@ sub ReadDatabase($)
 {
     my $datfile = shift;
     # open geolocation database and verify header
-    open DATFILE, "<$datfile" or warn("Error reading $datfile\n"), return 0;
+    open DATFILE, "< $datfile" or warn("Error reading $datfile\n"), return 0;
     binmode DATFILE;
     my $line = <DATFILE>;
     unless ($line =~ /^Geolocation(\d+\.\d+)\t(\d+)/) {
@@ -123,20 +136,23 @@ sub ReadDatabase($)
         close(DATFILE);
         return 0;
     }
-    if ($1 != $databaseVersion) {
-        my $which = $1 < $databaseVersion ? 'database' : 'ExifTool';
+    ($dbVer, $nCity) = ($1, $2);
+    if ($dbVer !~ /^1\.0[23]$/) {
+        my $which = $dbVer < 1.03 ? 'database' : 'ExifTool';
         warn("Incompatible Geolocation database (update your $which)\n");
         close(DATFILE);
         return 0;
     }
-    my $ncity = $2;
     my $comment = <DATFILE>;
-    defined $comment and $comment =~ /(\d+)/ or close(DATFILE), return 0;
-    $dbInfo = "$datfile v$databaseVersion: $ncity cities with population > $1";
+    defined $comment and $comment =~ / (\d+) / or close(DATFILE), return 0;
+    $dbInfo = "$datfile v$dbVer: $nCity cities with population > $1";
     my $isUserDefined = @Image::ExifTool::UserDefined::Geolocation;
-    
+
+    undef @altNames;    # reset altNames
+
     # read city database
     undef @cityList;
+    my $i = 0;
     for (;;) {
         $line = <DATFILE>;
         last if length($line) == 6 and $line =~ /\0\0\0\0/;
@@ -144,7 +160,7 @@ sub ReadDatabase($)
         chomp $line;
         push @cityList, $line;
     }
-    @cityList == $ncity or warn("Bad number of entries in Geolocation database\n"), return 0;
+    @cityList == $nCity or warn("Bad number of entries in Geolocation database\n"), return 0;
     # read countries
     for (;;) {
         $line = <DATFILE>;
@@ -177,10 +193,62 @@ sub ReadDatabase($)
         push @timezoneList, $line;
         $timezoneNum{lc $line} = $#timezoneList if $isUserDefined;
     }
+    # read feature codes if available
+    if ($line eq "\0\0\0\0\x05\n") {
+        undef @featureCodes;
+        for (;;) {
+            $line = <DATFILE>;
+            last if length($line) == 6 and $line =~ /\0\0\0\0/;
+            chomp $line;
+            $line =~ s/ .*//;  # (hook to be able to add feature descriptions later)
+            push @featureCodes, $line;
+        }
+    }
     close DATFILE;
+    # initialize featureCodes lookup
+    $i = 0;
+    %featureCodes = map { lc($_) => $i++ } @featureCodes;
     return 1;
 }
 
+#------------------------------------------------------------------------------
+# Read alternate-names database
+# Returns: True on success
+# Notes: Must be called after ReadDatabase(). Resets $altDir on exit.
+sub ReadAltNames()
+{
+    my $success;
+    if ($altDir and $nCity) {
+        if (open ALTFILE, "< $altDir/AltNames.dat") {
+            binmode ALTFILE;
+            local $/ = "\0";
+            my $i = 0;
+            while (<ALTFILE>) { chop; $altNames[$i++] = $_; }
+            close ALTFILE;
+            if ($i == $nCity) {
+                $success = 1;
+            } else {
+                warn("Bad number of entries in AltNames database\n");
+                undef @altNames;
+            }
+        } else {
+            warn "Error reading $altDir/AltNames.dat\n";
+        }
+        undef $altDir;
+    }
+    return $success;
+}
+
+#------------------------------------------------------------------------------
+# Clear last city matches cache
+sub ClearLastMatches()
+{
+    undef $lastArgs;    # arguments in last call to Geolocate
+    undef %lastFound;   # keys are last matching city numbers, values are population codes
+    undef @lastByPop;   # last matching city numbers ordered by population
+    undef @lastByLat;   # last matching city numbers ordered by latitude
+}
+
 #------------------------------------------------------------------------------
 # Sort database by specified field
 # Inputs: 0) Field name to sort (Latitude,City,Country)
@@ -189,38 +257,47 @@ sub SortDatabase($)
 {
     my $field = shift;
     return 1 if $field eq $sortedBy;    # already sorted?
+    undef @sortOrder;
     if ($field eq 'Latitude') {
-        @cityList = sort { $a cmp $b } @cityList;
+        @sortOrder = sort { $cityList[$a] cmp $cityList[$b] } 0..$#cityList;
     } elsif ($field eq 'City') {
-        @cityList = sort { substr($a,13) cmp substr($b,13) } @cityList;
+        @sortOrder = sort { substr($cityList[$a],13) cmp substr($cityList[$b],13) } 0..$#cityList;
     } elsif ($field eq 'Country') {
         my %lkup;
-        foreach (@cityList) {
-            my $city = substr($_,13);
-            my $ctry = substr($countryList[ord substr($_,5,1)], 2);
+        foreach (0..$#cityList) {
+            my $city = substr($cityList[$_],13);
+            my $ctry = substr($countryList[ord substr($cityList[$_],5,1)], 2);
             $lkup{$_} = "$ctry $city";
         }
-        @cityList = sort { $lkup{$a} cmp $lkup{$b} } @cityList;
+        @sortOrder = sort { $lkup{$a} cmp $lkup{$b} } 0..$#cityList;
     } else {
         return 0;
     }
     $sortedBy = $field;
+    ClearLastMatches();
     return 1;
 }
 
 #------------------------------------------------------------------------------
 # Add cities to the Geolocation database
-# Inputs: 0-8) city,region,subregion,country_code,country,timezone,feature_code,population,lat,lon
+# Inputs: 0-8) city,region,subregion,country_code,country,timezone,feature_code,population,lat,lon,altNames
 # eg. AddEntry('Sinemorets','Burgas','Obshtina Tsarevo','BG','Bulgaria','Europe/Sofia','',400,42.06115,27.97833)
+# Returns: true on success, otherwise issues warning
 sub AddEntry(@)
 {
-    my ($city, $region, $subregion, $cc, $country, $timezone, $fc, $pop, $lat, $lon) = @_;
-    @_ < 10 and warn("Too few arguments in $city definition (check for updated format)\n"), return;
-    if (@_ != 10 or length($cc) != 2) {
-        warn "Country code '${cc}' in UserDefined::Geolocation is not 2 characters\n";
-        return;
+    my ($city, $region, $subregion, $cc, $country, $timezone, $fc, $pop, $lat, $lon, $altNames) = @_;
+    @_ < 10 and warn("Too few arguments in $city definition (check for updated format)\n"), return 0;
+    length($cc) != 2 and warn("Country code '${cc}' is not 2 characters\n"), return 0;
+    $fc =~ s/ .*//; # (allow for descriptions to be added after a space -- future feature?)
+    my $fn = $featureCodes{lc $fc};
+    unless (defined $fn) {
+        if ($dbVer eq '1.02' or @featureCodes > 0x3f or not length $fc) {
+            $fn = 0;
+        } else {
+            push @featureCodes, uc($fc);
+            $featureCodes{lc $fc} = $fn = $#featureCodes;
+        }
     }
-    $fc = $featureCodes{lc $fc} || 0;
     chomp $lon; # (just in case it was read from file)
     # create reverse lookups for country/region/subregion/timezone if not done already
     # (eg. if the entries are being added manually instead of via UserDefined::Geolocation)
@@ -233,6 +310,7 @@ sub AddEntry(@)
     }
     my $cn = $countryNum{lc $cc};
     unless (defined $cn) {
+        $#countryList >= 0xff and warn("AddEntry: Too many countries\n"), return 0;
         push @countryList, "$cc$country";
         $cn = $countryNum{lc $cc} = $#countryList;
     } elsif ($country) {
@@ -240,16 +318,20 @@ sub AddEntry(@)
     }
     my $tn = $timezoneNum{lc $timezone};
     unless (defined $tn) {
+        $#timezoneList >= 0x1ff and warn("AddEntry: Too many time zones\n"), return 0;
         push @timezoneList, $timezone;
         $tn = $timezoneNum{lc $timezone} = $#timezoneList;
     }
     my $rn = $regionNum{lc $region};
     unless (defined $rn) {
+        $#regionList >= 0xfff and warn("AddEntry: Too many regions\n"), return 0;
         push @regionList, $region;
         $rn = $regionNum{lc $region} = $#regionList;
     }
     my $sn = $subregionNum{lc $subregion};
     unless (defined $sn) {
+        my $max = $dbVer eq '1.02' ? 0x7fff : 0xffff;
+        $#subregionList >= $max and warn("AddEntry: Too many subregions\n"), return 0;
         push @subregionList, $subregion;
         $sn = $subregionNum{lc $subregion} = $#subregionList;
     }
@@ -257,40 +339,67 @@ sub AddEntry(@)
     # pack CC index, population and region index into a 32-bit integer
     my $code = ($cn << 24) | (substr($pop,-1,1)<<20) | (substr($pop,0,1)<<16) | (substr($pop,2,1)<<12) | $rn;
     # store high bit of timezone index
-    $tn > 255 and $sn |= 0x8000, $tn -= 256;
+    if ($tn > 255) {
+        if ($dbVer eq '1.02') {
+            $sn |= 0x8000;
+        } else {
+            $fn |= 0x80;
+        }
+        $tn -= 256;
+    }
     $lat = int(($lat + 90)  / 180 * 0x100000 + 0.5) & 0xfffff;
     $lon = int(($lon + 180) / 360 * 0x100000 + 0.5) & 0xfffff;
-    my $hdr = pack('nCnNnCC', $lat>>4, (($lat&0x0f)<<4)|($lon&0x0f), $lon>>4, $code, $sn, $tn, $fc);
+    my $hdr = pack('nCnNnCC', $lat>>4, (($lat&0x0f)<<4)|($lon&0x0f), $lon>>4, $code, $sn, $tn, $fn);
     push @cityList, "$hdr$city";
+    # add altNames entry if provided
+    if ($altNames) {
+        chomp $altNames; # (just in case)
+        $altNames =~ tr/,/\n/;
+        # add any more arguments in case altNames were passed separately (undocumented)
+        foreach (11..$#_) {
+            chomp $_[$_];
+            $altNames .= "\n$_[$_]";
+        }
+        $altNames[$#cityList] = $altNames;
+    }
     $sortedBy = '';
+    undef $lastArgs;    # (faster than ClearLastArgs)
+    return 1;
 }
 
 #------------------------------------------------------------------------------
 # Unpack entry in database
-# Inputs: 0) entry number, 1) optional language code
-# Returns: 0-9) city,region,subregion,country_code,country,timezone,feature_code,pop,lat,lon
-sub GetEntry($;$)
+# Inputs: 0) entry number or index into sorted database,
+#         1) optional language code, 2) flag to use index into sorted database
+# Returns: 0-10) city,region,subregion,country_code,country,timezone,
+#                feature_code,pop,lat,lon,altNames
+sub GetEntry($;$$)
 {
-    my ($entryNum, $lang) = @_;
+    my ($entryNum, $lang, $sort) = @_;
     return() if $entryNum > $#cityList;
-    my ($lt,$f,$ln,$code,$sb,$tn,$fc) = unpack('nCnNnCC', $cityList[$entryNum]);
+    $entryNum = $sortOrder[$entryNum] if $sort and @sortOrder > $entryNum;
+    my ($lt,$f,$ln,$code,$sn,$tn,$fn) = unpack('nCnNnCC', $cityList[$entryNum]);
     my $city = substr($cityList[$entryNum],13);
     my $ctry = $countryList[$code >> 24];
     my $rgn = $regionList[$code & 0x0fff];
-    my $sub = $subregionList[$sb & 0x7fff];
+    if ($dbVer eq '1.02') {
+        $sn & 0x8000 and $tn += 256, $sn &= 0x7fff;
+    } else {
+        $fn & 0x80 and $tn += 256;
+    }
+    my $sub = $subregionList[$sn];
     # convert population digits back into exponent format
     my $pop = (($code>>16 & 0x0f) . '.' . ($code>>12 & 0x0f) . 'e+' . ($code>>20 & 0x0f)) + 0;
-    $tn += 256 if $sb & 0x8000;
     $lt = sprintf('%.4f', (($lt<<4)|($f >> 4))  * 180 / 0x100000 - 90);
     $ln = sprintf('%.4f', (($ln<<4)|($f & 0x0f))* 360 / 0x100000 - 180);
-    $fc = $featureCodes[$fc & 0x0f];
+    my $fc = $featureCodes[$fn & 0x3f] || 'Other';
     my $cc = substr($ctry, 0, 2);
     my $country = substr($ctry, 2);
     if ($lang) {
         my $xlat = $langLookup{$lang};
         # load language lookups if  not done already
         if (not defined $xlat) {
-            if (eval "require '$geoLang/$lang.pm'") {
+            if (eval "require '$geoDir/GeoLang/$lang.pm'") {
                 my $trans = "Image::ExifTool::GeoLang::${lang}::Translate";
                 no strict 'refs';
                 $xlat = \%$trans if %$trans;
@@ -325,30 +434,43 @@ sub GetEntry($;$)
     return($city,$rgn,$sub,$cc,$country,$timezoneList[$tn],$fc,$pop,$lt,$ln);
 }
 
+#------------------------------------------------------------------------------
+# Get alternate names for specified database entry
+# Inputs: 0) entry number or index into sorted database, 1) sort flag
+# Returns: comma-separated list of alternate names, or empty string if no names
+# Notes: ReadAltNames() must be called before this
+sub GetAltNames($;$)
+{
+    my ($entryNum, $sort) = @_;
+    $entryNum = $sortOrder[$entryNum] if $sort and @sortOrder > $entryNum;
+    my $alt = $altNames[$entryNum] or return '';
+    $alt =~ tr/\n/,/;
+    return $alt;
+}
+
 #------------------------------------------------------------------------------
 # Look up lat,lon or city in geolocation database
 # Inputs: 0) "lat,lon", "city,region,country", etc, (city must be first)
-#         1) optional min population, 2) optional max distance (km)
-#         3) optional language code, 4) flag to return multiple cities
-#         5) comma-separated list of feature codes to match (or ignore if leading "-")
-# Returns: Reference to list of city information, or list of city information
-#          lists if returning multiple cities.
-# City information list elements:
-#         0) UTF8 city name (or undef if geolocation is unsuccessful),
-#         1) UTF8 state, province or region (or empty),
-#         2) UTF8 subregion (or empty)
-#         3) country code, 4) country name,
-#         5) time zone name (empty string possible), 6) feature code, 7) population,
-#         8/9) approx lat/lon (or undef if geolocation is unsuccessful,
-#         10) approx distance (km), 11) compass bearing to city,
-#         12) non-zero if multiple matches were possible (and city with
-#             the largest population is returned)
-sub Geolocate($;$$$$$)
+#         1) options hash reference (or undef for no options)
+# Options: GeolocMinPop, GeolocMaxDist, GeolocMulti, GeolocFeature, GeolocAltNames,
+#          GeolocNearby
+# Returns: List of matching city information, empty if none found.
+#          Each element in the list is an array with 0=index of city in database,
+#          1=distance in km (or undef if no distance), 2=compass bearing (or undef)
+sub Geolocate($;$)
 {
-    my ($arg, $pop, $maxDist, $lang, $multi, $fcodes) = @_;
-    my ($city, $i, %found, @exact, %regex, @multiCity, $other, $idx);
-    my ($minPop, $minDistU, $minDistC, @matchParms, @matches, @coords, $fcmask, $both);
+    my ($arg, $opts) = @_;
+    my ($city, @exact, %regex, @multiCity, $other, $idx, @cargs, $useLastFound);
+    my ($minPop, $minDistU, $minDistC, @matchParms, @coords, %fcOK, $both);
+    my ($pop, $maxDist, $multi, $fcodes, $altNames, @startTime);
 
+    $opts and ($pop, $maxDist, $multi, $fcodes, $altNames) =
+        @$opts{qw(GeolocMinPop GeolocMaxDist GeolocMulti GeolocFeature GeolocAltNames)};
+
+    if ($debug) {
+        require Time::HiRes;
+        @startTime = Time::HiRes::gettimeofday();
+    }
     @cityList or warn('No Geolocation database'), return();
     # make population code for comparing with 2 bytes at offset 6 in database
     if ($pop) {
@@ -357,17 +479,18 @@ sub Geolocate($;$$$$$)
     }
     if ($fcodes) {
         my $neg = $fcodes =~ s/^-//;
-        my @fcodes = split /\s*,\s*/, $fcodes;
+        my @fcodes = split /\s*,-?\s*/, lc $fcodes;     # (allow leading dash on subsequent codes)
         if ($neg) {
-            $fcmask = 0xffff;
-            defined $featureCodes{lc $_} and $fcmask &= ~((1 << $featureCodes{lc $_})) foreach @fcodes;
+            $fcOK{$_} = 1 foreach 0..$#featureCodes;
+            defined $featureCodes{$_} and delete $fcOK{$featureCodes{$_}} foreach @fcodes;
         } else {
-            defined $featureCodes{lc $_} and $fcmask |= (1 << $featureCodes{lc $_}) foreach @fcodes;
+            defined $featureCodes{$_} and $fcOK{$featureCodes{$_}} = 1 foreach @fcodes;
         }
     }
 #
 # process input argument
 #
+    my $num = 1;
     $arg =~ s/^\s+//; $arg =~ s/\s+$//; # remove leading/trailing spaces
     my @args = split /\s*,\s*/, $arg;
     my %ri = ( cc => 0, co => 1, re => 2, sr => 3, ci => 8, '' => 9 );
@@ -376,18 +499,25 @@ sub Geolocate($;$$$$$)
         if (m{^(-)?(\w{2})?/(.*)/(i?)$}) {
             my $re = $4 ? qr/$3/im : qr/$3/m;
             next if not defined($idx = $ri{$2});
+            push @cargs, $_;
             $other = 1 if $idx < 5;
             $idx += 10 if $1;   # add 10 for negative matches
+            $regex{$idx} or $regex{$idx} = [ ];
             push @{$regex{$idx}}, $re;
             $city = '' unless defined $city;
         } elsif (/^[-+]?\d+(\.\d+)?$/) {    # coordinate format
             push @coords, $_ if @coords < 2;
-        } elsif (lc eq 'both') {
+        } elsif (lc $_ eq 'both') {
             $both = 1;
-        } elsif ($city) {
-            push @exact, lc $_;
-        } else {
-            $city = lc $_;
+        } elsif ($_ =~ /^num=(\d+)$/i) {
+            $num = $1;
+        } elsif ($_) {
+            push @cargs, $_;
+            if ($city) {
+                push @exact, lc $_;
+            } else {
+                $city = lc $_;
+            }
         }
     }
     unless (defined $city or @coords == 2) {
@@ -400,16 +530,34 @@ sub Geolocate($;$$$$$)
 # perform reverse Geolocation lookup to determine GPS based on city, country, etc.
 #
     while (defined $city and (@coords != 2 or $both)) {
-Entry:  for ($i=0; $i<@cityList; ++$i) {
+        my $cargs = join(',', @cargs, $pop||'', $maxDist||'', $fcodes||'');
+        my $i = 0;
+        if ($lastArgs and $lastArgs eq $cargs) {
+            $i = @cityList; # bypass search
+        } else {
+            ClearLastMatches();
+            $lastArgs = $cargs;
+        }
+        # read alternate names database if an exact city match is specified
+        if ($altNames) {
+            ReadAltNames() if $city and $altDir;
+            $altNames = \@altNames;
+        } else {
+            $altNames = [ ];    # (don't search alt names)
+        }
+Entry:  for (; $i<@cityList; ++$i) {
             my $cty = substr($cityList[$i],13);
-            next if $city and $city ne lc $cty; # test exact city name first
+            if ($city and $city ne lc $cty) { # test exact city name first
+                next unless $$altNames[$i] and $$altNames[$i] =~ /^$city$/im;
+            }
             # test with city-specific regexes
             if ($regex{8})  { $cty =~ $_ or next Entry foreach @{$regex{8}} }
             if ($regex{18}) { $cty !~ $_ or next Entry foreach @{$regex{18}} }
             # test other arguments
-            my ($cd,$sb) = unpack('x5Nn', $cityList[$i]);
+            my ($cd,$sn) = unpack('x5Nn', $cityList[$i]);
             my $ct = $countryList[$cd >> 24];
-            my @geo = (substr($ct,0,2), substr($ct,2), $regionList[$cd & 0x0fff], $subregionList[$sb & 0x7fff]);
+            $sn &= 0x7fff if $dbVer eq '1.02';
+            my @geo = (substr($ct,0,2), substr($ct,2), $regionList[$cd & 0x0fff], $subregionList[$sn]);
             if (@exact) {
                 # make quick lookup for all names at this location
                 my %geoLkup;
@@ -428,22 +576,21 @@ Entry:  for ($i=0; $i<@cityList; ++$i) {
                 $str !~ $_ or next Entry foreach @{$regex{19}};
             }
             # test feature code and population
-            next if $fcmask and not $fcmask & (1 << (ord(substr($cityList[$i],12,1)) & 0x0f));
+            next if $fcodes and not $fcOK{ord(substr($cityList[$i],12,1)) & 0x3f};
             my $pc = substr($cityList[$i],6,2);
-            $found{$i} = $pc if not defined $minPop or $pc ge $minPop;
+            if (not defined $minPop or $pc ge $minPop) {
+                $lastFound{$i} = $pc;
+                push @lastByLat, $i if @coords == 2;
+            }
         }
-        if (%found) {
-            @matches = keys %found;
-            @coords == 2 and @matches = sort({ $a <=> $b } @matches), last; # continue to use coords
-            scalar(keys %found) > 200 and warn("Too many matching cities\n"), return();
-            @matches = sort { $found{$b} cmp $found{$a} or $cityList[$a] cmp $cityList[$b] } @matches if @matches > 1;
-            foreach (@matches) {
-                my @cityInfo = GetEntry($_, $lang);
-                $cityInfo[12] = @matches if @matches > 1;
-                return \@cityInfo unless @matches > 1 and $multi;
-                push @multiCity, \@cityInfo;
+        @startTime and printf("= Processing time: %.3f sec\n", Time::HiRes::tv_interval(\@startTime));
+        if (%lastFound) {
+            @coords == 2 and $useLastFound = 1, last; # continue to use coords with last city matches
+            scalar(keys %lastFound) > 200 and warn("Too many matching cities\n"), return();
+            unless (@lastByPop) {
+                @lastByPop = sort { $lastFound{$b} cmp $lastFound{$a} or $cityList[$a] cmp $cityList[$b] } keys %lastFound;
             }
-            return \@multiCity;
+            return(\@lastByPop);
         }
         warn "No such city in Geolocation database\n";
         return();
@@ -465,12 +612,14 @@ Entry:  for ($i=0; $i<@cityList; ++$i) {
     $lon = int(($lon + 180) / 360 * 0x100000 + 0.5) & 0xfffff;
     $lat or $lat = $coords[0] < 0 ? 1 : 0xfffff;    # (zero latitude is a problem for our calculations)
     my $coord = pack('nCn',$lat>>4,(($lat&0x0f)<<4)|($lon&0x0f),$lon>>4);;
+    # start from cached city matches if also using city information
+    my $numEntries = @lastByLat || @cityList;
     # binary search to find closest longitude
-    my $numEntries = @matches || @cityList;
     my ($n0, $n1) = (0, $numEntries - 1);
+    my $sorted = @lastByLat ? \@lastByLat : (@sortOrder ? \@sortOrder : undef);
     while ($n1 - $n0 > 1) {
         my $n = int(($n0 + $n1) / 2);
-        if ($coord lt $cityList[@matches ? $matches[$n] : $n]) {
+        if ($coord lt $cityList[$sorted ? $$sorted[$n] : $n]) {
             $n1 = $n;
         } else {
             $n0 = $n;
@@ -480,43 +629,71 @@ Entry:  for ($i=0; $i<@cityList; ++$i) {
     my ($inc, $end, $n) = (-1, -1, $n0+1);
     my ($p0, $t0) = ($lat*$pi/0x100000 - $pi/2, $lon*$pi/0x080000 - $pi);
     my $cp0 = cos($p0);
+    my (@matches, @rtnList, @dist);
+
     for (;;) {
         if (($n += $inc) == $end) {
-            last if $inc == 1;
+            last if $inc == 1 or $n0 == $n1;
             ($inc, $end, $n) = (1, $numEntries, $n1);
         }
-        my $entryNum = @matches ? $matches[$n] : $n;
+        my $i = $sorted ? $$sorted[$n] : $n;
         # get city latitude/longitude
-        my ($lt,$f,$ln) = unpack('nCn', $cityList[$entryNum]);
+        my ($lt,$f,$ln) = unpack('nCn', $cityList[$i]);
         $lt = ($lt << 4) | ($f >> 4);
         # searched far enough if latitude alone is further than best distance
         abs($lt - $lat) > $minDistC and $n = $end - $inc, next;
         # ignore if population is below threshold
-        next if defined $minPop and $minPop ge substr($cityList[$entryNum],6,2);
-        next if $fcmask and not $fcmask & (1 << (ord(substr($cityList[$entryNum],12,1)) & 0x0f));
+        next if defined $minPop and $minPop ge substr($cityList[$i],6,2);
+        next if $fcodes and not $fcOK{ord(substr($cityList[$i],12,1)) & 0x3f};
         $ln = ($ln << 4) | ($f & 0x0f);
         # calculate great circle distance to this city on unit sphere
         my ($p1, $t1) = ($lt*$pi/0x100000 - $pi/2, $ln*$pi/0x080000 - $pi);
         my ($sp, $st) = (sin(($p1-$p0)/2), sin(($t1-$t0)/2));
         my $a = $sp * $sp + $cp0 * cos($p1) * $st * $st;
-        my $distU = atan2(sqrt($a), sqrt(1-$a));
+        my $distU = atan2(sqrt($a), sqrt(1-$a)); # distance on unit sphere
         next if $distU > $minDistU;
-        $minDistU = $distU;
-        $minDistC = $minDistU * 0x200000 / $pi;
-        @matchParms = ($entryNum, $p1, $t1, $distU);
+        @matchParms = ($i, $p1, $t1, $distU);
+        if ($num <= 1) {
+            $minDistU = $distU;
+        } else {
+            my $j;
+            # add this entry into list of matching cities ordered by closest first
+            for ($j=0; $j<@matches; ++$j) {
+                last if $distU < $matches[$j][3];
+            }
+            if ($j < $#matches) {
+                splice @matches, $j, 0, [ @matchParms ];
+            } else {
+                $matches[$j] = [ @matchParms ];
+            }
+            # restrict list to the specified number of nearest cities
+            pop @matches if @matches > $num;
+            # update minimum distance with furthest match if we satisfied our quota
+            $minDistU = $matches[-1][3] if @matches >= $num;
+        }
+        $minDistC = $minDistU * 0x200000 / $pi;  # distance in scaled coordinate units
     }
     @matchParms or warn("No suitable location in Geolocation database\n"), return();
+    $num = @matches;
 
-    # calculate distance in km and bearing to matching city
-    my ($en, $p1, $t1, $distU) = @matchParms;
-    my $km = sprintf('%.2f', 2 * $earthRadius * $distU);
-    my $be = atan2(sin($t1-$t0)*cos($p1-$p0), $cp0*sin($p1)-sin($p0)*cos($p1)*cos($t1-$t0));
-    $be = int($be * 180 / $pi + 360.5) % 360; # convert from radians to integer degrees
+    @startTime and printf("- Processing time: %.3f sec\n", Time::HiRes::tv_interval(\@startTime));
 
-    # unpack return values from database entry
-    my @cityInfo = GetEntry($en, $lang);
-    @cityInfo[10,11] = ($km, $be);   # add distance and heading
-    return \@cityInfo;
+    for (;;) {
+        if ($num > 1) {
+            last unless @matches;
+            @matchParms = @{$matches[0]};
+            shift @matches;
+        }
+        # calculate distance in km and bearing to matching city
+        my ($ii, $p1, $t1, $distU) = @matchParms;
+        my $km = sprintf('%.2f', 2 * $earthRadius * $distU);
+        my $be = atan2(sin($t1-$t0)*cos($p1-$p0), $cp0*sin($p1)-sin($p0)*cos($p1)*cos($t1-$t0));
+        $be = int($be * 180 / $pi + 360.5) % 360; # convert from radians to integer degrees
+        push @rtnList, $ii;
+        push @dist, [ $km, $be ];
+        last if $num <= 1;
+    }
+    return(\@rtnList, \@dist);
 }
 
 1; #end
@@ -525,11 +702,13 @@ __END__
 
 =head1 NAME
 
-Image::ExifTool::Geolocation - Look up geolocation based on GPS position
+Image::ExifTool::Geolocation - Determine geolocation from GPS and visa-versa
 
 =head1 SYNOPSIS
 
-This module is used by the Image::ExifTool Geolocation feature.
+Look up geolocation information (city, region, subregion, country, etc)
+based on input GPS coordinates, or determine GPS coordinates based on city
+name, etc.
 
 =head1 DESCRIPTION
 
@@ -562,6 +741,29 @@ True on success.
 
 =back
 
+=head2 ReadAltNames
+
+Load the alternate names database.  Before calling this method the $altDir
+package variable may be set, otherwise AltNames.dat is loaded from the same
+directory as Geolocation.dat.  This method is called automatically by
+L</Geolocate> if the GeolocAltNames option is used and an input city name is
+provided.
+
+    Image::ExifTool::Geolocation::ReadAltNames();
+
+=over 4
+
+=item Inputs:
+
+(none)
+
+=item Return Value:
+
+True on success.  May be called repeatedly, but AltNames.dat is loaded only
+on the first call.
+
+=back
+
 =head2 SortDatabase
 
 Sort database in specified order.
@@ -585,8 +787,8 @@ Sort database in specified order.
 Add entry to Geolocation database.
 
     Image::ExifTool::Geolocation::AddEntry($city, $region,
-        $countryCode, $country, $timezone, $featureCode
-        $population, $lat, $lon);
+        $subregion, $countryCode, $country, $timezone,
+        $featureCode, $population, $lat, $lon, $altNames);
 
 =over 4
 
@@ -614,23 +816,32 @@ database, then the database entry is updated with the new country name.
 
 9) GPS longitude
 
+10) Optional comma-separated list of alternate names for the city
+
+=item Return Value:
+
+1 on success, otherwise sends a warning message to stderr
+
 =back
 
 =head2 GetEntry
 
 Get entry from Geolocation database.
 
-    my @vals = Image::ExifTool::Geolocation::GetEntry($num,$lang);
+    my @vals = Image::ExifTool::Geolocation::GetEntry($num,$lang,$sort);
 
 =over 4
 
 =item Inputs:
 
-0) Entry number in database
+0) Entry number in database, or index into sorted database
 
 1) Optional language code
 
-=item Return Values:
+2) Optional flag to treat first argument as an index into the sorted
+database
+
+item Return Values:
 
 0) City name, or undef if the entry didn't exist
 
@@ -652,11 +863,30 @@ Get entry from Geolocation database.
 
 9) GPS longitude
 
+=back
+
+=head2 GetAltNames
+
+Get alternate names for specified city.
+
+    my $str = Image::ExifTool::Geolocation::GetAltNames($num,$sort);
+
+=over 4
+
+=item Inputs:
+
+0) Entry number in database or index into the sorted database
+
+1) Optional flag to treat first argument as an index into the sorted
+database
+
+=item Return value:
+
+Comma-separated string of alternate names for this city.
+
 =item Notes:
 
-The alternate-language feature of this method (and of L</Geolocate>)
-requires the installation of optional GeoLang modules.  See
-L<https://exiftool.org/geolocation.html> for more information.
+L</ReadAltNames> must be called before calling this routine.
 
 =back
 
@@ -664,8 +894,7 @@ L<https://exiftool.org/geolocation.html> for more information.
 
 Return geolocation information for specified GPS coordinates or city name.
 
-    my @cityInfo =
-        Image::ExifTool::Geolocation::Geolocate($arg,$pop,$dist,$lang,$multi,$codes);
+    my @rtnInfo = Image::ExifTool::Geolocation::Geolocate($arg,$opts);
 
 =over 4
 
@@ -677,57 +906,80 @@ zero or more of the following in any order, separated by commas: region
 name, subregion name, country code, and/or country name.  Regular
 expressions in C</expr/> format are also allowed, optionally prefixed by
 "ci", "re", "sr", "cc" or "co" to specifically match City, Region,
-Subregion, CountryCode or Country name.  See
-L<https://exiftool.org/geolocation.html#Read> for details.
-
-1) Minimum city population (cities smaller than this are ignored)
-
-2) Maximum distance to city (farther cities are not considered)
+Subregion, CountryCode or Country name.  Two special controls may be added
+to the argument list:
 
-3) Language code
+   'both'   - When search input includes both name and GPS coordinates, use
+              both to determine the closest city matching the specified
+              name(s) instead of using GPS only.
 
-4) Flag to return multiple cities if there is more than one match.  In this
-case the return value is a list of city information lists.
+   'num=##' - When the search includes GPS coordinates, return the nearest
+              ## cities instead of just the closest one.  Returned cities
+              are in the order from nearest to farthest.
 
-5) Comma-separated list of feature codes to include in search, or to exclude
-if the list starts with a dash (-).
+See L<https://exiftool.org/geolocation.html#Read> for more details.
 
-=item Return Value:
+1) Optional reference to hash of options:
 
-Reference to list of information about the matching city.  If multiple
-matches were found, the city with the highest population is returned unless
-the flag is set to allow multiple cities to be returned, in which case all
-cities are turned as a list of city lists in order of decreasing population.
+    GeolocMinPop   - Minimum population of cities to consider in search.
+                     Default 0.
 
-The city information list contains the following entries:
+    GeolocMaxDist  - Maximum distance (km) to search for cities when an
+                     input GPS position is used.  Default infinity.
 
-0) Name of matching city (UTF8), or undef if no match
+    GeolocMulti    - Flag to return multiple cities if there is more than
+                     one match.  Used in the case where no input GPS
+                     coordinates are provided.  Default 0.
 
-1) Region, state or province name (UTF8), or "" if no region
+    GeolocFeature  - Comma-separated list of feature codes to include in
+                     search, or exclude if the list starts with a dash (-).
+                     Default undef.
 
-2) Subregion name (UTF8), or "" if no region
+    GeolocAltNames - Flag to search alternate names database if available
+                     for matching city name (see ALTERNATE DATABASES below).
+                     Default undef.
 
-3) Country code
+=item Return Values:
 
-4) Country name (UTF8)
+0) Reference to list of database entry numbers for matching cities, or undef
+if no matches were found.
 
-5) Standard time zone identifier name
+1) Reference to list of distance/bearing pairs for each matching city, or
+undef if the search didn't provide GPS coordinates.
 
-6) Feature code
+=back
 
-7) City population rounded to 2 significant figures
+=head1 ALTERNATE DATABASES
 
-8) Approximate city latitude (signed degrees)
+A different version of the cities database may be specified setting the
+package $geoDir variable before loading this module.  This directory should
+contain the Geolocation.dat file, and optionally a GeoLang directory for the
+language translations.  The $geoDir variable may be set to an empty string
+to disable loading of a database.
 
-9) Approximate city longitude
+When searching for a city by name, AltNames.dat is checked to provide
+additional possibilities for matches if the GeolocAltNames option is set and
+an AltNames.dat database exists.  The package $altDir variable may be set to
+specify a different directory for AltNames.dat, otherwise the
+Geolocation.dat directory is assumed.  The entries in AltNames.dat must
+match those in the currently loaded version of Geolocation.dat.
 
-10) Distance to city in km if "lat,lon" specified
+=head1 ADDING USER-DEFINED DATABASE ENTRIES
 
-11) Compass bearing for direction to city if "lat,lon" specified
+User-defined entries may be created by defining them using the following
+technique before the Geolocation module is loaded.
 
-12) Flag set if multiple matches were found
+    @Image::ExifTool::UserDefined::Geolocation = (
+        # city, region, subregion, country code, country, timezone,
+        ['Sinemorets','burgas','Obshtina Tsarevo','BG','','Europe/Sofia',
+        # feature code, population, lat, lon
+         'PPL',400,42.06115,27.97833],
+    );
 
-=back
+Similarly, user-defined language translations may be defined, and will
+override any existing translations.  Translations for the default 'en'
+language may also be specified.  See
+L<https://exiftool.org/geolocation.html#Custom> for more information.
 
 =head1 USING A CUSTOM DATABASE
 
@@ -737,24 +989,17 @@ the input arguments of the AddEntry method.
 
     $Image::ExifTool::Geolocation::geoDir = '';
     require Image::ExifTool::Geolocation;
-    open DFILE, "<$filename";
+    open DFILE, "< $filename";
     Image::ExifTool::Geolocation::AddEntry(split /,/) foreach <DFILE>;
     close DFILE;
 
-=head1 CUSTOM LANGUAGE TRANSLATIONS
-
-User-defined language translations may be added by defining
-%Image::ExifTool::Geolocation::geoLang before calling GetEntry() or
-Geolocate().  See L<http://exiftool.org/geolocation.html#Custom> for
-details.
-
 =head1 AUTHOR
 
 Copyright 2003-2024, Phil Harvey (philharvey66 at gmail.com)
 
 This library is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.  Geolocation.dat is based on data
-from geonames.org with a Creative Commons license.
+under the same terms as Perl itself.  The associated database files are
+based on data from geonames.org with a Creative Commons license.
 
 =head1 REFERENCES