PostSc...le::EPS(3pm)

🌸 NAME 🌸

PostScript::Simple::EPS — it's the EPS support bestie for PostScript::Simple, no cap. This is a section 3pm page from the User Contributed Perl Documentation, and it's here to make your EPS files slay inside your PostScript docs. 💅

---

✨ SYNOPSIS ✨

Okay so here's the whole vibe in one go:

    use PostScript::Simple;

    # create a new PostScript object
    $p = new PostScript::Simple(papersize => "A4",
                                colour => 1,
                                units => "in");

    # create a new page
    $p->newpage;

    # add an eps file
    $p->add_eps({xsize => 3}, "test.eps", 1,1);
    $p->add_eps({yscale => 1.1, xscale => 1.8}, "test.eps", 4,8);

    # create an eps object
    $e = new PostScript::Simple::EPS(file => "test.eps");
    $e->rotate(90);
    $e->xscale(0.5);
    $p->add_eps($e, 3, 3); # add eps object to postscript object
    $e->xscale(2);
    $p->add_eps($e, 2, 5); # add eps object to postscript object again

    # write the output to a file
    $p->output("file.ps");

---

💖 DESCRIPTION 💖

PostScript::Simple::EPS lets you drop EPS files into PostScript::Simple objects. And the included EPS files? They can be scaled, they can be rotated, and they can be placed literally anywhere inside a PostScript::Simple page. Main character energy fr. 👑

But listen, bestie, real talk: when you're using translate/scale/rotate, you will normally need to do the operations in the reverse order to that which you expect. That's just how it is. 😭

---

🎀 PREREQUISITES 🎀

This module requires PostScript::Simple, strict, Carp and Exporter.

🌈 EXPORT 🌈

None. That's it. Nothing exported, we're minimal like that. ✨

---

🦋 CONSTRUCTOR 🦋

new(options)

Makes you a brand new PostScript::Simple::EPS object. The options you can set are:

• file — the EPS file to be included. Either this or source must exist when the new method gets called.
• source — PostScript code for the EPS document. Either this or file must be set when new is called.
• clip — set it to 0 to disable clipping to the EPS bounding box. Default behaviour is to clip.

Example, bestie:

    $ps = new PostScript::Simple(landscape => 1,
                                 eps => 0,
                                 xsize => 4,
                                 ysize => 3,
                                 units => "in");

    $eps = new PostScript::Simple::EPS(file => "test.eps");

    $eps->scale(0.5);

That last bit scales the EPS file by x0.5 in both directions. 🫶

    $ps->newpage();
    $ps->importeps($eps, 1, 1);

Adds the EPS file to the PostScript document at coords (1,1).

    $ps->importepsfile("another.eps", 1, 2, 4, 4);

Easily add an EPS file to the PostScript document using bounding box (1,2),(4,4).

The methods importeps and importepsfile are described in the documentation of PostScript::Simple. Go check that page, iykyk. 💜

---

💅 OBJECT METHODS 💅

Heads up: all object methods return 1 for success or 0 in some error condition (like, e.g., insufficient arguments). And the error message text? Also drawn on the page. Yes really. 🙈

get_bbox

Returns the EPS bounding box, as specified on the %%BoundingBox line of the EPS file. Units are standard PostScript points.

Example:

    ($x1, $y1, $x2, $y2) = $eps->get_bbox();

width

Returns the EPS width, in PostScript points.

Example:

  print "EPS width is " . abs($eps->width()) . "\n";

height

Returns the EPS height, in PostScript points.

Example:

To scale $eps to 72 points high, do:

  $eps->scale(1, 72/$eps->height());

scale(x, y)

Scales the EPS file. Wanna scale in one direction only? Just specify 1 as the other scale. And if you want to scale the EPS file the same in both directions, you get the shortcut of only specifying the one value. Periodt. ⭐

Example:

    $eps->scale(1.2, 0.8); # make wider and shorter
    $eps->scale(0.5);      # shrink to half size

rotate(deg)

Rotates the EPS file by deg degrees anti-clockwise. The EPS file is rotated about it's own origin (as defined by it's bounding box). Wanna rotate by a particular co-ordinate (again, relative to the EPS file, not the main PostScript document)? Then use translate, too.

Example:

    $eps->rotate(180);        # turn upside-down

To rotate 30 degrees about point (50,50):

    $eps->translate(50, 50);
    $eps->rotate(30);
    $eps->translate(-50, -50);

translate(x, y)

Move the EPS file by x,y PostScript points.

Example:

    $eps->translate(10, 10);      # move 10 points in both directions

reset

Clears all translate, rotate and scale operations. Fresh start, clean slate, new era. 🧚

Example:

    $eps->reset();

load

Reads the EPS file into memory, so you save on reading it from file every single time if it's inserted many times into a document. Can not be used with preload.

preload(object)

Experimental 👀 — defines the EPS at in the document prolog, and just runs a command to insert it each time it is used. object is a PostScript::Simple object. If the EPS file is included more than once in the PostScript file then this will probably shrink the filesize quite a lot. Iconic, honestly.

Can not be used at the same time as load, or when using EPS objects defined from PostScript source.

Example:

    $p = new PostScript::Simple();
    $e = new PostScript::Simple::EPS(file => "test.eps");
    $e->preload($p);

---

💀 BUGS 💀

This is software in development; some current functionality may not be as expected, and/or may not work correctly. So like… be aware, bestie. 😭

---

👑 AUTHOR 👑

The PostScript::Simple::EPS module was written by Matthew Newton, after prods for such a feature from several people around the world. A useful importeps function that provides scaling and aspect ratio operations was gratefully received from Glen Harris, and merged into this module.

Copyright (C) 2002-2014 Matthew C. Newton

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.

This program 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 General Public License for more details, available at http://www.gnu.org/licenses/gpl.html.

Fr fr read the license, it's giving important. 🫶

---

🌈 SEE ALSO 🌈

• PostScript::Simple

---

Okay that's the whole page, you ate it. 💖 Written for perl v5.36.0, dated 2022-11-19 — this version of PostSc...le::EPS(3pm) is now officially your bestie. Mwah. 💅✨