File Coverage

blib/lib/OCR/OcrSpace.pm

Criterion	Covered	Total	%
statement	56	68	82.3
branch	20	32	62.5
condition	4	11	36.3
subroutine	11	11	100.0
pod	1	1	100.0
total	92	123	74.8

package OCR::OcrSpace;

use 5.006;
use strict;
use warnings;

use LWP::UserAgent;
use Carp qw( carp confess croak );

use vars qw($VERSION @EXPORT @ISA $BASE_URL);

@ISA = qw(Exporter);

@EXPORT = qw( get_result  $BASE_URL);
############################################################
# DEFAULT base url
############################################################
$BASE_URL = 'http://api.ocr.space/parse/image';

=head1 NAME

Apr-2020 @

OCR::OcrSpace - Perl Interface to access L

The free OCR API provides a simple way of parsing images and multi-page PDF documents (PDF OCR) and getting the extracted text results returned in a JSON format.

This module implemented the Post request only.

Extract text from images , pdf via ocr-space

=head1 VERSION

Version 0.01

=cut

our $VERSION = '0.01';

=head1 SYNOPSIS

    #using object oriented interaface
    use OCR::OcrSpace;

    my $ocrspace_obj = OCR::OcrSpace->new();

    my $param = {
        file                         => '/tmp/image.png',                     #full iamge path

                                    or

        url                         => 'http://imagedatabase.com/test.jpg'   #image url to fetch from

                                    or

        base64Image                 => 'data:image/png;base64,iVBORw0KGgoAx7/7LNuCQS0posnocgEAFpySUVORK5CYII='

        #following optional parameter
        ocr_space_url                  => "https://api.ocr.space/parse/image",
        apikey                         => 'XXXXXXXXXXXXXXXXXX',                 #API Key (mandatory)
        isOverlayRequired              =>'True',                                #optional
        language                       =>'eng' ,                                #optional
        scale                          => 'True',                               #optional
        isTable                        => 'True',                               #optional
        OCREngine                      => 2,                                    #optional
        filetype                       => 'PNG',                                #optional
        detectOrientation              => 'False',                              #optional
        isCreateSearchablePdf          => 'True',                               #optional
        isSearchablePdfHideTextLayer   => 'True',                               #optional

    };

    print $ocrspace_obj->get_result( $param );


    #using non-object oriented interaface

    use OCR::OcrSpace;
    print get_result( $param );



    #since ocrSpace uses http as well as HTTPs you can always set the following varible before call
    $BASE_URL

=head1 EXPORT

    #method
    get_result

    #varible
    $BASE_URL

=head1 SUBROUTINES/METHODS

=head2 new

    used to create a constructor of OCR::OcrSpace for object oriented mode

=cut

sub new {
    my ( $class, $params ) = ( @_ );

    return ( bless( {}, $class ) );
}

=head2 get_result

     params hash ref of following valid keys

=over 13

=item *  B  { optional but required when using object oriented interface }

=item *  B  { optional url if you want to use https mention url }

C scalar string ([Optional] Default  L)

=item *  B  { scalar string }

C API Key (send in the header)

get your key from here L

=item *   B

C
You can use three methods to upload the input image or PDF. We recommend the URL method for file sizes > 10 MB for faster upload speeds.

    url: URL of remote image file (Make sure it has the right content type)

    file: Multipart encoded image file with filename

    base64Image: Image as Base64 encoded string


=item * B

C

    [Optional]
    Arabic=ara
    Bulgarian=bul
    Chinese(Simplified)=chs
    Chinese(Traditional)=cht
    Croatian = hrv
    Czech = cze
    Danish = dan
    Dutch = dut
    English = eng
    Finnish = fin
    French = fre
    German = ger
    Greek = gre
    Hungarian = hun
    Korean = kor
    Italian = ita
    Japanese = jpn
    Polish = pol
    Portuguese = por
    Russian = rus
    Slovenian = slv
    Spanish = spa
    Swedish = swe
    Turkish = tur

Language used for OCR. If no language is specified, English eng is taken as default.

IMPORTANT: The language code has always 3-letters (not 2). So it is "eng" and not "en".

=item *  B

C scalar string ([Optional] Boolean value)


Default = False
If true, returns the coordinates of the bounding boxes for each word. If false, the OCR'ed text is returned only as a text block (this makes the JSON reponse smaller). Overlay data can be used, for example, to show text over the image.


=item *  B

C scalar string  (Optional] String value: PDF, GIF, PNG, JPG, TIF, BMP)

Overwrites the automatic file type detection based on content-type. Supported image file formats are png, jpg (jpeg), gif, tif (tiff) and bmp. For document ocr, the api supports the Adobe PDF format. Multi-page TIFF files are supported.


=item *  B

C scalar string ([Optional] true/false)


if set to true, the api autorotates the image correctly and sets the TextOrientation parameter in the JSON response. If the image is not rotated, then TextOrientation=0, otherwise it is the degree of the rotation, e. g. "270".


=item *  B

C scalar string ([Optional] Boolean value)

Default = False
If true, API generates a searchable PDF. This parameter automatically sets isOverlayRequired = true


=item *  B

C scalar string ([Optional] Boolean value)

Default = False. If true, the text layer is hidden (not visible)


=item *  B

C scalar string ([Optional] true/false)


If set to true, the api does some internal upscaling. This can improve the OCR result significantly, especially for low-resolution PDF scans. Note that the front page demo uses scale=true, but the API uses scale=false by default. See also this OCR forum post.


=item *  B

C scalar string ([Optional] true/false)

If set to true, the OCR logic makes sure that the parsed text result is always returned line by line. This switch is recommended for table OCR, receipt OCR, invoice processing and all other type of input documents that have a table like structure.

=item *  B

C scalar int ([Optional] 1 or 2)

The default is engine 1. OCR Engine 2 is a new image-processing method.


=back

=head2 Notes from L

Tip: When serving images from an Amazon AWS S3 bucket or a similar service for use with the "URL" parameter, make sure it has the right content type. It should not be "Content-Type:application/x-www-form-urlencoded" (which seems to be the default) but image/png or similar. Alternatively you can include the filetype parameter and tell the API directly what type of document you are sending (PNG, JPG, GIF, PDF).


New: If you need to detect the status of checkboxes, please contact us about the Optical Mark Recognition (OMR) (Beta) features.


Select the best OCR Engine

New: We implemented a second OCR engine with a different processing logic. It is better than the default engine (engine1) in certain cases. So we recommend that you try engine1 first (since it is faster), but if the OCR results are not perfect, please try the same document with engine2. You can use the new OCR engine with our free online OCR service on the front page, and with the API.

Features of OCR Engine 1:

- Supports more languages (including Asian languages like Chinese, Japanese and Korean)

- Faster

- Supports larger images

- PDF OCR and Searchable PDF creation support

- Multi-Page TIFF scan support

- Parameter: OCREngine=1

Features of OCR Engine 2:

- Western Latin Character languages only (English, German, French,...)

- Language auto-detect (so it does not really matter what OCR language you select, as long as it uses Latin characters)

- Usually better at single number OCR and alphanumeric OCR (e. g. SUDOKO, Dot Matrix OCR, MRZ OCR,... )

- Usually better at special characters OCR like @+-...

- Image size limit 5000px width and 5000px height

- Parameter: OCREngine=2

- No PDF OCR and Offline OCR yet. If you need this, please contact us for an internal beta.

The returned OCR result JSON response is identical for both engines! So you can easily switch between both engines as needed. If you have any question about using Engine 1 or 2, please ask in our OCR API Forum.


=cut

sub get_result {

    #can be simply done by discarding the $self
    # but keeping it like this to allow future maintaince if any
    my ( $params, $raw_request, $result );
    if ( scalar @_ > 1 ) {
        my $self;
        ( $self, $params ) = ( @_ );

        #validate the parameters and get
        $params = $self->_validate( $params );

        #Generate the request
        $raw_request = $self->_generate_request( $params );

        #send the request via gateway
        $result = $self->_process_request( $raw_request );

    } else {
        $params = shift;

        $params = _validate( $params );

        #Generate the request
        $raw_request = _generate_request( $params );

        #send the request via gateway
        $result = _process_request( $raw_request );
    }

    #retun
    return $result // undef;

}

=head2 Sample Ouput success

    {"ParsedResults":[{"TextOverlay":{"Lines":[{"LineText":"Current","Words":[{"WordText":"Current","Left":11.666666030883789,"Top":59.166664123535156,"Height":14.999999046325684,"Width":54.999996185302734}],"MaxHeight":14.999999046325684,"MinTop":59.166664123535156},{"LineText":"59","Words":[{"WordText":"59","Left":32.5,"Top":239.99998474121094,"Height":20.833332061767578,"Width":29.166666030883789}],"MaxHeight":20.833332061767578,"MinTop":239.99998474121094}],"HasOverlay":true,"Message":"Total lines: "2"},"TextOrientation":"0","FileParseExitCode":1,"ParsedText":"Current\t\r\n59\t\r\n","ErrorMessage":"","ErrorDetails":""}],"OCRExitCode":1,"IsErroredOnProcessing":false,"ProcessingTimeInMilliseconds":"437","SearchablePDFURL":""}

=head2 Sample Ouput error

    {"OCRExitCode":99,"IsErroredOnProcessing":true,"ErrorMessage":["Parameter name 'attributes' is invalid. Valid parameters: apikey,url,language,isoverlayrequired,base64image,iscreatesearchablepdf,issearchablepdfhidetextlayer,filetype,addressparsing,scale,detectorientation,istable,ocrengine,detectcheckbox,checkboxtemplate,checkboxtemplateregex","Please check if you need to URL encode the URL passed in request parameters."],"ProcessingTimeInMilliseconds":"0"}

=cut

####################
# internal function
###################
sub _generate_request {
    my $params = ( scalar( @_ ) > 1 ) ? $_[1] : shift;

    my $request_hash = {
        url        => $params->{endpoint},
        body_param => $params->{body_param},
    };

    $request_hash->{file_path} = $params->{file} if ( defined $params->{file} );

    return $request_hash;
}

####################
# internal function
###################
sub _validate {
    my $params = ( scalar( @_ ) > 1 ) ? $_[1] : shift;
    carp "Required parameter `apikey` not passed" unless ( defined $params->{apikey} );
    carp "Required parameter `url or file or base64Image` not passed"
      unless ( defined( $params->{url} || $params->{file} || $params->{base64Image} ) );

    my $valid_params = { endpoint => $params->{ocr_space_url} // $BASE_URL, };
    $valid_params->{url}         = $params->{url}         if ( defined $params->{url} );
    $valid_params->{base64Image} = $params->{base64Image} if ( defined $params->{base64Image} );
    if ( defined $params->{file} ) {
        if ( -f $params->{file} ) {
            $valid_params->{file} = $params->{file};
        } else {
            carp "Unable to open file $params->{file} \n";
        }
    }

    #add optional keys
    foreach (
        qw/
        language                      isOverlayRequired       filetype
        detectOrientation             isCreateSearchablePdf   url
        isSearchablePdfHideTextLayer  scale                   base64Image
        isTable                       OCREngine               apikey/
      )
    {
        $valid_params->{body_param}->{$_} = $params->{$_} if ( defined $params->{$_} );
    }
    return $valid_params;
}

####################
# internal function
###################
sub _process_request {
    my $params = ( scalar( @_ ) > 1 ) ? $_[1] : shift;

    my $file     = $params->{file_path};
    my $endpoint = $params->{url};

    my ( $res, $body, $header, $content );

    if ( defined $params->{body_param} && uc( ref( $params->{body_param} ) ) eq 'HASH' ) {
        foreach ( keys %{ $params->{body_param} } ) {
            push( @$content, ( $_ => $params->{body_param}->{$_} ) );
        }
    }

    if ( $file ) {
        push( @$content, ( file => [$file] ) );
    }

    my $ua = LWP::UserAgent->new();

    $ua->env_proxy;

    if ( defined $params->{header} ) {
        $header = $params->{header};
        $ua->default_header( %$header );
    }

    foreach ( 1 .. 3 ) {
        $res = $ua->post(
            $endpoint,
            Content_Type => 'multipart/form-data',
            Content      => $content,
        );

        if ( $res->is_success ) {
            return $res->content;
        } else {
            return $res->status_line;
        }
    }
}

=head1 AUTHOR

sushrut pajai, C<<  >>

=head1 BUGS

Please report any bugs or feature requests to C, or through
the web interface at L.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.


=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc OCR::OcrSpace


You can also look for information at:

=over 4

=item * RT: CPAN's request tracker (report bugs here)

L

=item * AnnoCPAN: Annotated CPAN documentation

L

=item * CPAN Ratings

L

=item * Search CPAN

L

=back


=head1 ACKNOWLEDGEMENTS


=head1 LICENSE AND COPYRIGHT

This software is copyright (c) 2020 by sushrut pajai.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.


=cut

1;    # End of OCR::OcrSpace

__END__