Can you reduce the program to a very short program that still exhibits the problem? I'm thinking of something like:

#!perl
use strict;
use warnings;
use PDF::API2;

print "Using PDF::API2 version $PDF::API2::VERSION\n";

my $pdf = PDF::API2->new;
my $bg_file = 'watermark.pdf';
my $bg = $pdf->importPageIntoForm( $bg_file, 1 );

# ...

$page->gfx->formimage( $bg, 0, 0, 1.0 )

# write to another file
[download]

That would help me understand your steps better and maybe point out where the problem(s) might lie.

Aha, this was a helpful kick in the pants. When I do a simple script as you suggest, everything works swimmingly. So there's something in the home-grown modules in between, that we are using, that's corrupting things. So at least I have a starting point for sleuthing now.

One thing I've noticed in the past, is that I must disable $pdf->{forcecompress} = 0. Sometimes it's okay even with forcecompress left enabled, other times it really scrambles the presentation when displaying via a PDF reader (text enormous or skewed or mispositioned on the page). Turning it off makes it so there's dependable display of the results.

Is that common -- where forcecompress causes issues?

Presuming some form of *NIX if you're completely at a dead end sometimes using strace (or dtruss on OS X) can be enlightening. For something like this you're mainly interested in the lists of files which it tries to call open(2) or stat(2) or the like on. Run on both machines and then compare the two; sometimes it helps to do some post-processing to remove differences (common things would be to smash out the exact file descriptors run returned or addresses of buffers passed and get (say) a list of the files it can or can't open; possibly run those lists through sort and uniq before diff'ing can help).

Edit: a word.

Good ideas. I hope I can resolve it noodling thru my perl code before getting elbow deep in strace, tho. Thanks for the suggestions! :)

And perhaps the cake is just an exaggeration.