lib/Image/OpenALPR.pm

   1 package Image::OpenALPR;
   2
   3 use 5.014000;
   4 use strict;
   5 use warnings;
   6
   7 use Image::OpenALPR::PlateResult;
   8 use JSON::MaybeXS qw/decode_json/;
   9 use XSLoader;
  10
  11 BEGIN {
  12         our $VERSION = '0.001';
  13         XSLoader::load('Image::OpenALPR', $VERSION);
  14         *initialise         = \&initialize;
  15         *is_loaded          = \&isLoaded;
  16         *get_version        = \&getVersion;
  17         *set_country        = \&setCountry;
  18         *set_prewarp        = \&setPrewarp;
  19         *set_default_region = \&setDefaultRegion;
  20         *set_top_n          = \&setTopN;
  21 }
  22
  23 sub new {
  24         my $alpr = initialise (@_[1..$#_]);
  25         die "Failed to load OpenALPR\n" unless $alpr->is_loaded;
  26         $alpr
  27 }
  28
  29 sub recognise {
  30         my ($alpr, $data) = @_;
  31         my $json = ref $data eq 'SCALAR' ? $alpr->recognizeArray($$data) : $alpr->recognizeFile($data);
  32         $json = decode_json $json;
  33         my @plates = map { Image::OpenALPR::PlateResult->new($_) } @{$json->{results}};
  34         wantarray ? @plates : shift @plates
  35 }
  36
  37 sub DESTROY { shift->dispose }
  38
  39 package AlprPtr;
  40 our @ISA = qw/Image::OpenALPR/;
  41
  42 1;
  43 __END__
  44
  45 =encoding utf-8
  46
  47 =head1 NAME
  48
  49 Image::OpenALPR - Perl binding for Automatic License Plate Recognition library
  50
  51 =head1 SYNOPSIS
  52
  53   use Image::OpenALPR;
  54   my $alpr = Image::OpenALPR->new('eu');
  55   $alpr->get_version; # 2.2.4
  56   my (@plates) = $alpr->recognise('many_plates.jpg');
  57   say 'Plates found: ', join ' ', map { $_->plate } @plates;
  58
  59   $alpr->set_top_n(2);
  60   my $data = read_file 'one_plate.gif';
  61   my $a_plate  = $alpr->recognise(\$data);
  62   my @cnd = @{$a_plate->candidates};
  63   say $cnd[0]->plate, ' ', $cnd[0]->confidence;
  64   say $cnd[1]->plate, ' ', $cnd[1]->confidence;
  65
  66 =head1 DESCRIPTION
  67
  68 OpenALPR is an automatic license plate recognition library that
  69 extracts license plate numbers from images.
  70
  71 The following methods are available:
  72
  73 =over
  74
  75 =item Image::OpenALPR->B<new>(I<$country>, I<$config>, I<$runtime_data>)
  76
  77 Takes one mandatory argument (the country rules to use, such as C<eu>
  78 or C<us>) and two optional arguments: a path to the configuration
  79 file, and a path to the runtime_data directory.
  80
  81 Returns a new Image::OpenALPR instance. If initialisation fails (for
  82 example, if the chosen country is not available) an exception is
  83 thrown.
  84
  85 =item $alpr->B<recognise>(I<$file>)
  86
  87 =item $alpr->B<recognise>(I<\$data>)
  88
  89 Takes a path to an image file or a reference to the contents of an
  90 image file and tries to find license plates in the image. In list
  91 context, it returns a list of L<Image::OpenALPR::PlateResult> objects,
  92 one for each plate found. In scalar context it returns only one such
  93 object (the first plate found), or undef if no plates were found.
  94
  95 =item $alpr->B<get_version>
  96
  97 =item $alpr->B<getVersion>
  98
  99 Returns the version of the OpenALPR library.
 100
 101 =item $alpr->B<set_country>(I<$country>)
 102
 103 =item $alpr->B<setCountry>(I<$country>)
 104
 105 Changes the country rules in use.
 106
 107 =item $alpr->B<set_prewarp>(I<$prewarp>)
 108
 109 =item $alpr->B<setPrewarp>(I<$prewarp>)
 110
 111 Sets the camera calibration values, as obtained from the
 112 C<openalpr-utils-calibrate> utility. Can also be set in the
 113 configuration file.
 114
 115 =item $alpr->B<set_default_region>(I<$region>)
 116
 117 =item $alpr->B<setDefaultRegion>(I<$region>)
 118
 119 Sets the expected region for pattern matching. This improves accuracy.
 120 The B<matches_template> flag is set on plates that match this pattern.
 121
 122 =item $alpr->B<set_top_n>(I<$n>)
 123
 124 =item $alpr->B<setTopN>(I<$n>)
 125
 126 Sets the maximum number of candidates to return for one plate. Default
 127 is 10.
 128
 129 =back
 130
 131 =head1 SEE ALSO
 132
 133 L<http://www.openalpr.com>, L<https://github.com/openalpr/openalpr>
 134
 135 =head1 AUTHOR
 136
 137 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 138
 139 =head1 COPYRIGHT AND LICENSE
 140
 141 Copyright (C) 2016 by Marius Gavrilescu
 142
 143 This file is part of Image-OpenALPR.
 144
 145 Image-OpenALPR is free software: you can redistribute it and/or modify
 146 it under the terms of the GNU Affero General Public License as published by
 147 the Free Software Foundation, either version 3 of the License, or
 148 (at your option) any later version.
 149
 150 Image-OpenALPR is distributed in the hope that it will be useful,
 151 but WITHOUT ANY WARRANTY; without even the implied warranty of
 152 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 153 GNU Affero General Public License for more details.
 154
 155 You should have received a copy of the GNU Affero General Public License
 156 along with Image-OpenALPR.  If not, see <http://www.gnu.org/licenses/>
 157
 158
 159 =cut