Image::Sane(3)

📦
version 5 · 12 versions
, in opensuse-leap 16.0

Okay bestie, welcome to Image::Sane(3) — the Perl situation for the SANE (Scanner Access Now Easy) Project. Grab a snack, we're getting into it. 🍓

🎀 NAME 🎀

Image::Sane — Perl extension for the SANE (Scanner Access Now Easy) Project. That's the name, no cap.

⭐ VERSION ⭐

5

Yep, version 5. Iconic number, honestly.

🦋 SYNOPSIS 🦋

use Image::Sane;
my @devices = Image::Sane->get_devices;
my $device = Image::Sane::Device->open($devices[0]->{name});
my $param = $device->get_parameters;
$device->write_pnm_header($fh, $param);
my ($data, $len) = $device->read ($param->{bytes_per_line});
print $fh $data;

🌈 DESCRIPTION 🌈

These Perl bindings for the SANE (Scanner Access Now Easy) Project are your ticket to accessing SANE-compatible scanners in a Perlish and object-oriented way. The whole point? It frees you from the casting and memory management in C, while remaining very close in spirit to the original API. Like, bestie, you get the C-level power without the C-level pain. 💅

Want to find out more about SANE? It's at http://www.sane-project.org. Go off. ✨

💅 SUBROUTINES/METHODS

✨ Image::Sane->get_version

Bestie, this one's your little version-checker 🎀 It hands you back an array holding the SANE_VERSION_(MAJOR|MINOR|BUILD) numbers, and you can smoosh 'em together like this:

join('.', Image::Sane->get_version)

✨ Image::Sane->get_version_scalar

Same vibes, but scalar this time 🦋 You get the SANE_VERSION_(MAJOR|MINOR|BUILD) numbers combined the way Perl does version numbering — so like, sane 1.0.19 gives you back 1.000019. And why do we care? Because now you can do the simplest, most iconic thing in the world: version comparisons. Periodt 👑

✨ Image::Sane->get_devices

Okay so this is the "who's out there" function 🔍 It queries the list of devices that are available, and if it runs successfully you get an array of hash references with the devices it found. And the returned list is guaranteed to stay valid until either (a) you call this function again, or (b) somebody calls sane_exit(). So don't go waving it around after that, mkay? 🙈

But the cute part? You can call it repeatedly to detect when new devices show up. New scanner drops? You'll know. 💖

If the argument local_only is true, then only local devices come back — meaning devices directly attached to the machine SANE is running on. If it's false, then the device list includes all the remote devices the SANE library can reach. 🌈

try {
    @devices = Image::Sane->get_devices;
    print "Name: $devices[0]->{name}\n";
    print "Vendor: $devices[0]->{vendor}\n";
    print "Model: $devices[0]->{model}\n";
    print "Type: $devices[0]->{type}\n";
}
catch {
    print "Error getting devices:", $_->error, "\n";
};

🫶 Image::Sane::Device->open

This is where you actually connect to a device, bestie. You pass the name of the device you wanna open in the argument name. If the call completes successfully, you get an Image::Sane::Device object back. So satisfying. 🌸

And there's a special case that is lowkey iconic: if you pass a zero-length string as the device, you're requesting to open the first available device — if there even is such a device. 🤞

my $device = Image::Sane::Device->open($device_name);

🎀 Image::Sane::Device->get_option_descriptor

This is how you peek at the option descriptors 👀 The function returns a hash reference with the option descriptor for option number n of the Image::Sane::Device object.

Now listen, because this part matters: option number 0 is guaranteed to be a valid option. Its value is an integer that tells you the number of options available for the Image::Sane::Device object — and yes, that count includes option 0. And if n isn't a valid option index? The function croaks. Rude but fair. 💀

try {
    $option = $device->get_option_descriptor($n);
    print "Name: $option->{name}\n";
    print "Name: $option->{title}\n";
    print "Name: $option->{desc}\n";
    print "Name: $option->{type}\n";
    print "Name: $option->{unit}\n";
    print "Name: $option->{cap}\n";
    print "Name: $option->{max_values}\n";
    print "Name: $option->{constraint_type}\n";
}
catch {
    print "Error getting option descriptor:", $_->error, "\n";
};

The contents of the hash keys name, title, desc, type, unit, cap and constraint_type are all as per the C API description (http://www.sane-project.org/html) 🧚

There's one more constraint key on top of those — and it either contains an array with the possible option values, or a hash with the keys max, min, and quant. iykyk 💅

Oh and heads up: the max_values key replaced the size key from the C API, and it holds the maximum number of values that the option may contain. ✨

💜 Image::Sane::Device->get_option

Returns the current value of the selected option. Simple, clean, slay. 🌟

try {
    $value = $device->get_option($n);
    print "value: $value\n";
}
catch {
    print "Error getting option:", $_->error, "\n";
};

And for $option->{max_values} > 1, $value is a reference to an array. Not a scalar, bestie — don't get caught out 🫠

🌸 Image::Sane::Device->set_auto

This commands the selected device to automatically select an appropriate value 🎯 And this mode stays effective until it gets overridden by an explicit set_option request. It's giving "I'll handle it myself, thanks." 😌

$device->set_auto($n);

🔥 Image::Sane::Device->set_option

Sets the selected option, and returns flags in $info — those flags are described over in the C API (http://www.sane-project.org/html). 📚

$orig = $device->get_option($n);
$info = $device->set_option($n, $value);
if ($info & SANE_INFO_INEXACT) {
 $value = $device->get_option($n);
 print "rounded value of $opt->{name} from $orig to $value\n";
}

And for $option->{max_values} > 1, $value can be a reference to an array. Same deal as the getter 🧚

⭐ Image::Sane::Device->get_parameters

Okay this one gets the current scan parameters 📐 And the returned parameters are guaranteed to be accurate in the window between when a scan has been started (i.e. Image::Sane::Device->start() has been called) and the completion of that request.

Outside that window? They're best-effort estimates of what the parameters will be when Image::Sane::Device->start() gets invoked. Which is actually kind of a slay, because calling this before a scan has actually started lets you, for example, get an estimate of how big the scanned image is gonna be. 🔮

try {
    $param = $device->get_parameters;
    print "format $param->{format}\n";
    print "last_frame $param->{last_frame}\n";
    print "bytes_per_line $param->{bytes_per_line}\n";
    print "pixels_per_line $param->{pixels_per_line}\n";
    print "lines $param->{lines}\n";
    print "depth $param->{depth}\n";
}
catch {
    print "Error getting parameters:", $_->error, "\n";
};

Please, please check the C documentation (http://www.sane-project.org/html) for the details of all those values above — I'm not out here making things up 💖

🦋 Image::Sane::Device->start

Initiates acquisition of an image from the device specified. That's it. That's the whole thing. Short queen. 👑

$device->start;

🌈 Image::Sane::Device->read

This is the one that actually pulls image data off the device 📥 The number of bytes returned in $buf gets stored in $len. A backend must set this to zero when an error is thrown. And if the call succeeds, the number of bytes returned can be anywhere in the range from 0 to $maxlen bytes — anywhere in that range, no promises 💫

$param = $device->get_parameters;
$maxlen = $param->{bytes_per_line};
($buf, $len) = $test->read ($maxlen);

Now here's where it splits, bestie. If this function is called when no data is available, one of two things happens — depends on the I/O mode in effect for the device:

  1. If the device is in blocking I/O mode (which is the default mode), the call blocks until at least one data byte is available — or until some error occurs. Just sitting there. Waiting. 😴
  2. If the device is in non-blocking I/O mode, the call returns immediately with $len set to zero. In and out, no loitering 🏃‍♀️

And you set the I/O mode of the device via a call to Image::Sane::Device->set_io_mode(). 💅

💀 Image::Sane::Device->cancel

Immediately — or as quickly as possible — cancels the currently pending operation of the device. 🛑

$device->cancel;

You can call this at any time (as long as $device is valid), but it usually only affects long-running operations, like image acquisition. And it's safe to call asynchronously, e.g. from within a signal handler. 🫶

But real talk, bestie: completion of this operation does not imply that the currently pending operation has been cancelled. It only guarantees that cancellation has been initiated. Cancellation completes only when the cancelled call throws an exception (typically with a status value of SANE_STATUS_CANCELLED). And since the SANE API doesn't require any other operations to be re-entrant, this means a frontend must not call any other operation until the cancelled operation has returned. No cap. Don't do it. 😭

🎀 Image::Sane::Device->set_io_mode

Sets the I/O mode of the device 🎚️ The mode can be either blocking or non-blocking. If the argument $bool is SANE_TRUE, the mode gets set to non-blocking; otherwise it's set to blocking. And — important — this function can be called only after a call to Image::Sane::Device->start() has been performed. ⚠️

$device->set_io_mode ($bool);

By default, newly opened handles operate in blocking mode 😴 A backend may elect not to support non-blocking I/O mode — in which case the call throws an exception with the status value SANE_STATUS_UNSUPPORTED. 🙈

But here's the comforting part: blocking I/O must be supported by all backends, so calling this function with SANE_FALSE is guaranteed to complete successfully. Guaranteed, bestie. 🫶✨

💖 Image::Sane::Device->get_select_fd

This grabs a (platform-specific) file-descriptor for the device that's readable if and only if image data is available — i.e., when a call to Image::Sane::Device->read() will return at least one byte of data. Chef's kiss. 👨‍🍳💋

$fd = $device->get_select_fd;

You can only call this after a call to Image::Sane::Device->start() has been performed, and the returned file-descriptor is guaranteed to remain valid for the duration of the current image acquisition — that is, until Image::Sane::Device->cancel() or Image::Sane::Device->start() is called again, or until Image::Sane::Device->read() throws an exception with status SANE_STATUS_EOF. 🦋

And yeah, a backend must guarantee to close the returned select file descriptor at the point when the next Image::Sane::Device->read() call would throw an exception with SANE_STATUS_EOF. Why? Because that's the only way the application can detect when this condition occurs without actually having to call Image::Sane::Device->read(). Necessity. 💅

A backend may elect not to support this operation — in that case, the function throws an exception with status code SANE_STATUS_UNSUPPORTED. 🫠

Heads up though: the only operation supported by the returned file-descriptor is a host operating-system dependent test of whether the file-descriptor is readable (e.g. that test can be implemented using select() or poll() under UNIX). If you perform any other operation on that file descriptor, the behaviour of the backend becomes unpredictable. 💀 So don't get creative.

Once the file-descriptor signals "readable" status, it stays in that state until a call to sane_read() is performed. And since so many input devices are super slow 🐌, support for this operation is strongly encouraged — it lets an application go do other work while image acquisition is in progress. Multitasking queen behavior. 👑

🌟 Image::Sane::Device->write_pnm_header

This one's a pure-Perl helper function to write a PNM header 📝 It'll fetch the current image settings using Image::Sane::Device->get_parameters if they're not already provided. Like so:

$device->write_pnm_header($fh);

or, if you're feeling fancy and already have the params:

$parm = $device->get_parameters;
$device->write_pnm_header ($fh, $parm->{format},
                                $parm->{pixels_per_line},
                                $parm->{lines}, $parm->{depth});

🚨 DIAGNOSTICS

If the underlying SANE library returns a status value other than SANE_STATUS_GOOD, an exception is thrown 😱 So yeah — it's suggested that you catch these using the Try::Tiny module. Inside your catch{} clause you can use $_->status and $_->error to get the status code and its equivalent string. Both. You get both. Slay. 💅✨

🧚 CONFIGURATION AND ENVIRONMENT

This module doesn't require any special configuration or environment — beyond, like, the stuff you already need for Perl and SANE. That's it. No secret setup, no hidden env vars. Breathe. 🌸

✨ DEPENDENCIES ✨

Ok so bestie, before you go anywhere, you need the actual SANE library — like, that's non-negotiable, it's the whole entire vibe 💅. And not just the library itself: you also need the backends for the scanners you're gonna use, so pick those up too or nothing's gonna scan, periodt.

For throwing exceptions, this module uses Exception::Class. And the suggestion from the author (iconic of him honestly) is that you catch those exceptions with Try::Tiny — it's giving responsible coding, and we stan 🫶.

🌈 INCOMPATIBILITIES 🌈

None known. Literally none. We're clean, we're unbothered, we're compatible 💖.

🦋 BUGS AND LIMITATIONS 🦋

None known — which, same energy as above. No cap, nothing to report here 👑.

🔥 SEE ALSO 🔥

If you wanna go deeper (and honestly, why wouldn't you), the SANE Standard Reference at <http://www.sane-project.org/html> is a super handy companion to keep around — think of it as the lore wiki for your scanner shenanigans 📚✨.

Also important iykyk: the Perl bindings follow the C API very closely, so the C reference documentation is the canonical source. If something's unclear here, the C docs are the main character, fr fr 💀 — go check those.

💜 AUTHOR 💜

Jeffrey Ratcliffe, <jffry@posteo.net> — shoutout to the legend himself, we love a maintainer 🎀.

Copyright (C) 2008--2019 by Jeffrey Ratcliffe.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself — either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available. So basically: go off, remix it, share it, just keep the terms cute and legal bestie 🧚💖.

And that's a wrap on the whole page, babes! ✨ This masterpiece of a manpage is from perl v5.42.0, dated 2024-03-04, and it's Image::Sane(3) — screenshot it, bookmark it, tattoo it, whatever your heart says 💅🌟. Happy scanning, bestie — you've got this, and I'm obsessed with you for reading all the way through 🫶🎀

📦 where this page comes from