PGPLOT(3pm)

💖 NAME 💖

PDL::Graphics::PGPLOT — the PGPLOT-enhanced interface for PDL, bestie. It's the plotting glow-up. ✨

---

🌸 SYNOPSIS 🌸

pdl> $x = pdl [1..100]
pdl> $y = sqrt($x)
pdl> line $y
pdl> hold
Graphics on HOLD
pdl> $c = sin($x/10)*2 + 4
pdl> line $c

okay that's literally the whole vibe in five lines 🫶

---

✨ DESCRIPTION ✨

PDL::Graphics::PGPLOT is a convenience interface to the PGPLOT commands, and it's implemented using the object oriented PGPLOT plotting package inside PDL::Graphics::PGPLOT::Window. If you want the deep lore — like, the in-depth info about how these commands actually work and what options they take — go read the docs for that package. That's where the tea is. 🍓

Here's the list of commands you can currently use, and no I'm not skipping any of them, we're doing all of them, periodt:

imag       -  Display an image (uses pgimag()/pggray() as appropriate)
im         -  Shorthand to display an image with aspect ratio of 1
fits_imag  -  Display a FITS image with appropriate transforms & labels
cont       -  Display image as contour map
fits_cont  -  Display a FITS image in scientific coordinates as a contour map
vect       -  Display 2 images as a vector field
fits_vect  -  Display 2 FITS images in sci. coordinates as a vector field
ctab       -  Load an image colour table
ctab_info  -  Get information about currently loaded colour table
line       -  Plot vector as connected points
points     -  Plot vector as points
errb       -  Plot error bars
bin        -  Plot vector as histogram (e.g. bin(hist($data)) )
hi2d       -  Plot image as 2d histogram (not very good IMHO...)
poly       -  Draw a polygon
text       -  Write text in the plot area
label_axes -  Print axis titles
legend     -  Create a legend with different texts, linestyles etc.
cursor     -  Interactively read cursor positions.
circle     -  Draw a circle
ellipse    -  Draw an ellipse.

And then the device manipulation girlies, aka the ones that move your plot window around like it's a group chat you're muting and unmuting:

hold         -  Hold current plot window range - allows overlays etc.
release      -  Release back to autoscaling of new plot window for each
                command
rel          -  short alias for 'release'
env          -  Define a plot window, put on 'hold'
dev          -  Explicitly set a new PGPLOT graphics device
new_window   -  Create a new plot window (use of dev is recommended)
focus_window -  Change focus to a new window
window_list  -  Get a list of currently existing plot windows
close_window -  Close an open window

---

👑 FUNCTIONS 👑

Everything below is a list of the functions that are private to this package. For everything else, please go read the PDL::Graphics::PGPLOT::Window documentation, bestie, that's where the rest of the menu lives. 💅

🦋 dev

Open a PGPLOT graphics device. Main character energy, honestly.

Usage: dev $device, [$nx,$ny, $opt];

$device is a PGPLOT graphics device such as "/xserve" or "/ps". If you leave it out, it defaults to the last device you used (or, if this is your very first time, the value of the env var PGPLOT_DEV). $nx and $ny specify sub-panelling. The function returns the id of the newly created window — and you can totally reuse that id later as an argument to focus_window to select the window. So useful, lowkey iconic.

You can modify the result of this command using options. The options it recognises are the same as for new_window — which, primarily and in addition, means it's possible to set the default values for a window that are defined in PDL::Graphics::PGPLOTOptions. Go read that for details, but there's a synopsis below too, don't worry. 🫶

On top of that, dev also recognises the option NewWindow, which lets you specify that a dev command should create a new window rather than closing the previous one. That means you can have a large number of output destinations open at the same time, which occasionally comes in clutch.

Here's a quick summary of the most useful additional options you can hand it:

• Device — an alternative to $device.
• AspectRatio — the aspect ratio of the output window.
• WindowWidth — the width of the plot window, in inches.
• AxisColour — the axis colour to be used as default for plots in this window. Same deal, you can also set the default character size (CharSize) and the axis and box styles. See PDL::Graphics::PGPLOTOptions for details.
• WindowName — the name of a window. You can use this name afterwards to refer to the window instead of its ID, which makes interactive use somewhat more intuitive. 💅

To open an X-window output that stays on screen:

$win = dev('/xs');

To open two windows, one small and square, one large and wide:

$win1 = dev('/xs', {Aspect => 1, WindowWidth => 4});
$win2 = dev('/xs', {Aspect => 0.5, WindowWidth => 10});

🎀 new_window

Open a PGPLOT graphics device.

$win = new_window($dev, $nx, $ny, $opt);

This function is identical to dev except that it always creates a new window. Which means you're required to close all windows explicitly using close_window. Everything else works just like dev, so go read the docs for dev for the details of use. No cap. ✨

💜 close_window

Close a PGPLOT output device.

Usage: close_window($id)

This function closes a PGPLOT output device created with dev or new_window. It requires the id of the window to close. If $id is left undefined, the currently focussed window gets deleted and focus is transferred to the lowest numbered window in existence. If you've created and deleted a bunch of windows this might not be what you expect, so it's recommended to make an explicit call to focus_window after any call to close_window.

⚠️ bestie listen — that "lowest numbered window in existence" thing is a trap if you've been opening and closing windows all over the place. Just call focus_window yourself, save your sanity. 🫠

🌈 _get_windownumber

Internal function to obtain the ID of a window. It's the little helper that lets you refer to a window by its name. Underrated, honestly. 🙈

⭐ focus_window

Switch to another output window.

Usage: focus_window($id);

This command is what you use to switch output focus to another window created by dev or new_window. You can refer to the window either by its ID or by its name.

$win1 = dev('/xs', {WindowName => 'X-output'});
$win2 = dev('test.ps/ps', {WindowName => 'PS-output'});

focus_window('X-output');  # Or focus_window($win1);
<.. Commands ..>
focus_window($win2);       # Or focus_window('PS-output');
<.. Commands ..>

Look at that. Two windows. Both getting their moment. We love to see it. 💖

🧚 window_list

Return a list of ID numbers and names of the windows currently opened using dev or new_window. A little census of your windows, if you will.

Usage: ($numbers, $names)=window_list();

$numbers and $names are anonymous arrays giving the ID numbers and names of the open windows respectively. Slay. 🎀

---

and that's the whole page, bestie, you made it to the end 🥳 this was PGPLOT(3pm) from the User Contributed Perl Documentation, and it shipped as part of perl v5.38.2, dated 2024-04-10. go forth and plot something gorgeous. 💅✨🦋