[image-openalpr.git] / lib / Image / OpenALPR.pm

package Image::OpenALPR;

use 5.014000;
use strict;
use warnings;

use Image::OpenALPR::PlateResult;
use JSON::MaybeXS qw/decode_json/;
use XSLoader;

BEGIN {
	our $VERSION = '0.001';
	XSLoader::load('Image::OpenALPR', $VERSION);
	*initialise         = \&initialize;
	*is_loaded          = \&isLoaded;
	*get_version        = \&getVersion;
	*set_country        = \&setCountry;
	*set_prewarp        = \&setPrewarp;
	*set_default_region = \&setDefaultRegion;
	*set_top_n          = \&setTopN;
}

sub new {
	my $alpr = initialise (@_[1..$#_]);
	die "Failed to load OpenALPR\n" unless $alpr->is_loaded;
	$alpr
}

sub recognise {
	my ($alpr, $data) = @_;
	my $json = ref $data eq 'SCALAR' ? $alpr->recognizeArray($$data) : $alpr->recognizeFile($data);
	$json = decode_json $json;
	my @plates = map { Image::OpenALPR::PlateResult->new($_) } @{$json->{results}};
	wantarray ? @plates : shift @plates
}

sub DESTROY { shift->dispose }

package AlprPtr;
our @ISA = qw/Image::OpenALPR/;

1;
__END__

=encoding utf-8

=head1 NAME

Image::OpenALPR - Perl binding for Automatic License Plate Recognition library

=head1 SYNOPSIS

  use Image::OpenALPR;
  my $alpr = Image::OpenALPR->new('eu');
  $alpr->get_version; # 2.2.4
  my (@plates) = $alpr->recognise('many_plates.jpg');
  say 'Plates found: ', join ' ', map { $_->plate } @plates;

  $alpr->set_top_n(2);
  my $data = read_file 'one_plate.gif';
  my $a_plate  = $alpr->recognise(\$data);
  my @cnd = @{$a_plate->candidates};
  say $cnd[0]->plate, ' ', $cnd[0]->confidence;
  say $cnd[1]->plate, ' ', $cnd[1]->confidence;

=head1 DESCRIPTION

OpenALPR is an automatic license plate recognition library that
extracts license plate numbers from images.

The following methods are available:

=over

=item Image::OpenALPR->B<new>(I<$country>, I<$config>, I<$runtime_data>)

Takes one mandatory argument (the country rules to use, such as C<eu>
or C<us>) and two optional arguments: a path to the configuration
file, and a path to the runtime_data directory.

Returns a new Image::OpenALPR instance. If initialization fails (for
example, if the chosen country is not available) an exception is
thrown.

=item $alpr->B<recognise>(I<$file>)

=item $alpr->B<recognise>(I<\$data>)

Takes a path to an image file or a reference to the contents of an
image file and tries to find license plates in the image. In list
context, it returns a list of L<Image::OpenALPR::PlateResult> objects,
one for each plate found. In scalar context it returns only one such
object (the first plate found), or undef if no plates were found.

=item $alpr->B<get_version>

=item $alpr->B<getVersion>

Returns the version of the OpenALPR library.

=item $alpr->B<set_country>(I<$country>)

=item $alpr->B<setCountry>(I<$country>)

Changes the country rules in use.

=item $alpr->B<set_prewarp>(I<$prewarp>)

=item $alpr->B<setPrewarp>(I<$prewarp>)

Sets the camera calibration values, as obtained from the
openalpr-utils-calibrate utility. Can also be set in the configuration
file.

=item $alpr->B<set_default_region>(I<$region>)

=item $alpr->B<setDefaultRegion>(I<$region>)

Sets the expected region for pattern matching. This improves accuracy.
The B<matches_template> flag is set on plates that match this pattern.

=item $alpr->B<set_top_n>(I<$n>)

=item $alpr->B<setTopN>(I<$n>)

Sets the maximum number of candidates to return for one plate. Default
is 10.

=back

=head1 SEE ALSO

L<http://www.openalpr.com>, L<https://github.com/openalpr/openalpr>

=head1 AUTHOR

Marius Gavrilescu, E<lt>marius@ieval.roE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2016 by Marius Gavrilescu

This file is part of Image-OpenALPR.

Image-OpenALPR is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

Image-OpenALPR is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with Image-OpenALPR.  If not, see <http://www.gnu.org/licenses/>


=cut
Commit	Line	Data
	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 initialization 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	openalpr-utils-calibrate utility. Can also be set in the configuration
	113	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