NAME

 Scanner::Format - Page Scan format class.

SYNOPSIS

 use Scanner::Format;

 $obj  = Scanner::Format->new ( list of named arguments );
         Scanner::Format->setDefaultCalibratorFlag;
         Scanner::Format->clrDefaultCalibratorFlag;
 $bool = Scanner::Format->defaultUnitsAre ( $myunits );
 $bool = Scanner::Format->defaultFormatIs ( $myformat );

 ($width, $height) = $obj->ScanDimensions;
 ($width, $height) = $obj->UserDimensions;
 $flg              = $obj->landscape;
 $flg              = $obj->portrait;
 $str              = $obj->orientation;
 $str              = $obj->format;
 $obj              = $obj->info ($str);

Inheritance

 UNIVERSAL

Description

This class is a representation of a format of a page.

Examples

 use Scanner::Format;

 my $flg = Scanner::Format->defaultUnitsAre ( "Inches" );
    $flg = Scanner::Format->defaultFormatIs ( "P:Letter" );
           Scanner::Format->setDefaultCalibratorFlag;

 my $obj    = Scanner::Format->new ('format' => "P:8.5x13.0");
 my ($x,$y) = $obj->ScanDimensions;

 if ($obj->landscape) {print "It is a landscape format.\n";}
 if ($obj->portrait ) {print "It is a portrait  format.\n";}

Class Variables

 DEFAULT_UNITS              Assume arguments to every new are in 
                            this unit. Default is mm.
 DEFAULT_FORMAT             If a new method does not specify a format
                            assume this format. Default is a Portrait
                            A4 page, ie 215.9 x 304.8 mm.
 DEFAULT_CALIBRATOR         Flag whether an extra inch or 25.4 mm
                            should be added to the bottom to allow for
                            calibration tools below the page. Default is 
                            off.

Instance Variables

 format         page format string
 calibrator     Flag  indicating whether extra space is left at the bottom.
 orientation    L for landscape and P for Portrait.
 height         Height of the page in default units, usually mm.
 width          Width of the page in default units, usually mm.
 papertype      a4, letter, etc. May be undefined.

Class Methods

$obj = Scanner::Format->new ( named argument list )

This is the Class method for creating new Scanner::Format objects. It may have many different arguments. They are in short:

                format     -> string          {OPT: default is "P:A4"]
                calibrator -> boolean         [OPT: default is 1]
                units      -> mm|inches       [OPT: default is "mm"]

'calibrator' => <boolean>

If set, add an extra inch below the page. The default value is false.

'units' => <units>

Sets the unit of measure to be used when interpreting the width and height parameters. Current choices are "mm" and "inches". The default value is "mm" since that is what the 'scanimage' program uses.

'format' => <formatstring>

A format string has two or 3 fields:

  <formatstring> := <orientation>:<papertype> | 
                    <orientation>:<scanwidth>x<scanheight>

where:

 <orientation>: is the page placement on the scanner, either L for landscape or 
                P for portrait.

 <papertype>:   allowed values at present are a4, letter and legal (case is ignored).

 <scanwidth>:   scan width of the page in the current units of measure and must be 
                greater than zero.

 <scanheight>:  scan height of the page in the current units of measure and must be 
                greater than zero.

All fields are case insensitive.

The default value is a portrait oritentation of an a4 paper type. The size is 8.5 inch * 25.4 mm/inch across the width of the scanner and 12.5 inch * 25.4 mm/inch down the length of the scanner.

'date' => <date string>

A date to be included as the first part of the page name, where a single date is represented as:

        yyyymmdd
        yyyymmddhhmmss

and mm and dd may be 00 to represent 'the whole month' or the 'whole year' as in a monthly magazine or a yearly report, or to represent uncertainty, 'it was from sometime in that year'. there may optionally be two dates, so as to represent a period of time associated with the page:

        date1-date2

Scanner::Format->setDefaultCalibratorFlag

Setting this will make every object created add an extra inch below each page unless specifically overridden by 'calibrator' => 0 when a new object is created.

The intent of this option is to leave space for placement of a size/color/aspect-ratio calibration devices in the scan field of view. Common image calibration devices are small color wheels, rulers, little square things like you see in photos by field Geologists, or perhaps a round coin to show aspect ratios. Such calibrators act are a permanent means of mapping an image to its real world original.

The feature is turned off by default. It may either be set on by default with this Class method, or turned on explicitly for particular page objects.

Scanner::Format->clrDefaultCalibratorFlag

The converse of the above. Since this is the default condition of the Class, you will only need to run this if you have executed a setDefaultCalibratorFlag somewhere in your code.

$bool = Scanner::Format->defaultUnitsAre ( $units )

Set the default units for height and width input values. Legal inputs are "mm" and "inches". Case is ignored. Any other value causes a false return.

If you do nothing, the class default is "mm" because the scanimage program assumes metric.

Returns true on success; false if no arg or it wasn't one of the two valid options.

$bool = Scanner::Format->defaultPaperTypeIs ( $papertype )

Set the default paper type. Legal values are "a4", "letter" or "legal". Case is ignored. Any other value causes a false return.

If you do nothing, the class default is "a4". Why? Because we used metric for the units default. Consistency is next to godliness I always say.

Instance Methods

$str = $obj->format

Return the current page scan format string.

$flg = $obj->info ($str)

Print a block of informational text to stdout:

    [$str Format]
    Format:                     P:8.5x12
    Scan Orientation:           P
    Paper type:                 undefined
    Scan width:                 8.5 Inches
    Scan length:                12 Inches
    Image Calibrator Margin:    0 Iinches

$flg = $obj->landscape

Return true if it uses a landscape page format.

$flg = $obj->orientation

Return the orientation string, "L" or "P".

$flg = $obj->portrait

Return true if it uses a portrait page format.

($width, $height) = $obj-Egt>ScanDimensions>

Retrieve the page dimensions to be used for scanning. The height may include extra space for calibration devices as earlier discussed in the Scanner::Format->setDefaultCalibratorFlag section:

        (width, height+calibratorheight)

The scanner might of course have something to say about the height or width we have selected! That, however, is not the Format's problem. It is what it is and it might be too large for the scanner you have.

($width, $height) = $obj-Egt>UserDimensions>

Retrieve the page dimensions as originally supplied by the user.

Private Class Methods

 None.

Private Instance Methods

 None.

Errors and Warnings

 None.

KNOWN BUGS

 See TODO.

SEE ALSO

 None.

AUTHOR

Dale Amon <amon@vnl.com>

cpanm Scanner::Job

perl -MCPAN -e shell
install Scanner::Job