pdlfunc - Functions in the PDL distribution
This is a listing of all documented functions in the PDL distribution.
Module: PDL::Graphics::PGPLOT::Window
This routine advances one plot panel, updating the CurrentPanel as well. If the advance will proceed past the page the page will be erased. Also note that when you advance one panel the hold value will be changed.
Module: PDL::Graphics::PGPLOT::Window
This routine is a utility routine which checks if we need to move panel, and if so will do this. It also checks if it is necessary to advance panels, and whether they need to be erased.
Module: PDL::Graphics::PGPLOT::Window
This routine checks and optionally alters the arguments given to it.
Module: PDL::Graphics::PGPLOT::Window
This routine takes and array and returns the first hash reference found as well as those elements that are not hashes. Note the latter point because all other references to hashes in the array will be lost.
Module: PDL::Graphics::PGPLOT::Window
Given a FITS image, return the PGPLOT transformation matrix to convert pixel coordinates to scientific coordinates. Used by fits_imag, fits_rgbi, and fits_cont, but may come in handy for other methods.
my $tr = _FITS_tr( $win, $img ); my $tr = _FITS_tr( $win, $img, $opts );
The return value ($tr in the examples above) is the same as
returned by the transform() routine, with values
set up to convert the pixel to scientific coordinate values for the
two-dimensional image $img. The $opts argument is optional
and should be a HASH reference; currently it only understands
one key (any others are ignored):
WCS => undef (default), "", or "A" to "Z"
Both the key name and value are case insensitive. If left as undef
or "" then the primary coordinate mapping from the header is used, otherwise
use the additional WCS mapping given by the appropriate letter.
We make no checks that the given mapping is available; the routine
falls back to the unit mapping if the specified system is not available.
The WCS option has only been tested on images from the Chandra X-ray satellite
(http://chandra.harvard.edu/) created by the CIAO software
package (http://cxc.harvard.edu/ciao/), for which you should
set WCS => "P" to use the PHYSICAL coordinate system.
See http://fits.cv.nrao.edu/documents/wcs/wcs.html for further information on the Representation of World Coordinate Systems in FITS.
Module: PDL::Graphics::PGPLOT
Internal function to obtain the ID of a window. This allows the user to refer to a window with its name.
Module: PDL::Graphics::PGPLOT::Window
Given a PGPLOT tr matrix and an image size, calculate the data world coordinates over which the image ranges. This is used in imag and cont. It keeps track of the required half-pixel offset to display images properly -- eg feeding in no tr matrix at all, nx=20, and ny=20 will will return (-0.5,19.5,-0.5,19.5). It also checks the options hash for XRange/YRange specifications and, if they are present, it overrides the appropriate output with the exact ranges in those fields.
Module: PDL::Graphics::PGPLOT::Window
Open a new window. This sets the window ID, which is the one used when
accessing a window later using pgslct. It also sets the window name
to something easily remembered if it has not been set before.
Module: PDL::Graphics::PGPLOT::Window
This is a convenience routine for parsing a set of options. It returns both the full set of options and those that the user has set.
Module: PDL::Graphics::PGPLOT::Window
Convert a unit string or number into a PGPLOT-certified length unit specification, or return undef if it won't go.
Module: PDL::IO::FITS
Accept a hash ref containing a table, and return a header describing the table and a string to be written out as the table, or barf.
You can indicate whether the table should be binary or ascii. The default is binary; it can be overridden by the ``tbl'' field of the hash (if present) or by parameter.
Module: PDL::Graphics::PGPLOT::Window
This functions reopens a window. Since this is an internal function it does not have a lot of error-checking. Make sure the device is closed before calling this routine.
There is an unfortunate problem which pops up viz. that the window name
cannot be changed at this point since we are offering that to the rest of
the world. That might be sensible, but it means that the window name will
not reflect the id of the window - use id() for that (this is also why
we do not call open_new_window )
Module: PDL::Graphics::PGPLOT::Window
Restore the PGPLOT state. See _save_status.
Module: PDL::IO::FITS
Return the number of rows in a variable for table entry
You feed in a PDL or a list ref, and you get back the 0th dimension.
Module: PDL::Graphics::PGPLOT::Window
Saves the PGPLOT state so that changes to settings can be made and then
the present state restored by _restore_status.
Module: PDL::Graphics::PGPLOT::Window
This is an internal routine that encapsulates all the nastiness of setting colours depending on the different PGPLOT colour models (although HLS is not supported).
The routine works in the following way:
At initialisation of the plot device the work colour index is set to 16. The work index is the index the routine will modify unless the user has specified something else.
The routine should be used after standard interpretation and synonym matching has been used. So if the colour is given as input is an integer that colour index is used.
If the colour is a reference the routine checks whether it is an
ARRAY or a PDL reference. If it is not an error message is given.
If it is a PDL reference it will be converted to an array ref.
If the array has four elements the first element is interpreted
as the colour index to modify and this overrules the setting for the
work index used internally. Otherwise the work index is used and incremented
until the maximum number of colours for the output device is reached
(as indicated by pgqcol). Should you wish to change that you need
to read the PGPLOT documentation - it is somewhat device dependent.
When the array has been recognised the R,G and B colours of the
user-set index or work index is set using the pgscr command and we
are finished.
If the input colour instead is a string we try to set the colour
using the PGPLOT routine pgscrn with no other error-checking. This
should be ok, as that routine returns a rather sensible error-message.
Module: PDL::Graphics::PGPLOT::Window
This routine sets up a new window with its shape and size. This is
also where the size options are actually parsed. These are then
forgotten (well, they are stored in $self->{Options}) and the
corresponding aspect ratio and window width is stored. See the
discussion under new() for the logic.
Finally the subpanels are set up using pgsubp and colours and linewidth
are adjusted according to whether we have a hardcopy device or not.
Module: PDL::Graphics::PGPLOT::Window
This internal routine is the default routine for parsing options. This routine deals with a subset of options that most routines will accept.
Module: PDL::Graphics::PGPLOT::Window
This routine checks PGPLOT's status for the window. It returns OPEN if the window is open and CLOSED if it is closed. (Windows can be closed but still exist).
Module: PDL::Graphics::PGPLOT::Window
This function is a cludgy utility function that expands an options hash to an array of hashes looping over options. This is mainly of use for ``threaded'' interfaces to standard plotting routines.
Module: PDL::IO::GD
$image->AABlend( )
Alias for gdImageAABlend.
Module: PDL::Ops
Signature: (a(); [o]b())
elementwise absolute value
$b = abs $a; $a->inplace->abs; # modify $a inplace
It can be made to work inplace with the $a->inplace syntax.
This function is used to overload the unary abs operator/function.
abs does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Math
Signature: (a(); [o]b())
The usual trigonometric function. Works inplace.
acos does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Math
Signature: (a(); [o]b())
The standard hyperbolic function. Works inplace.
acosh does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Graphics::TriD::Contours
Add labels to a contour plot
$contour->addlabels($labelint,$segint,$font);
$labelint is the integer interval between labeled contours. If you have 8 countour levels and specify $labelint=3 addlabels will attempt to label the 1st, 4th, and 7th contours. $labelint defaults to 1.
$segint specifies the density of labels on a single contour level. Each contour level consists of a number of connected line segments, $segint defines how many of these segments get labels. $segint defaults to 5, that is every fifth line segment will be labeled.
Module: PDL::Ufunc
Return true if all elements in piddle set
Useful in conditional expressions:
if (all $a>15) { print "all values are greater than 15\n" }
See and for comments on what happens when all elements in the check are bad.
Module: PDL::Basic
Generates a piddle with index values
$z = allaxisvals ($piddle);
allaxisvals produces an array with axis values along each dimension,
adding an extra dimension at the start.
allaxisvals($piddle)->slice("($nth)") will produce the same result
as axisvals($piddle,$nth) (although with extra work and not inplace).
It's useful when all the values will be required, as in the example given of a generalized rvals.
Module: PDL::IO::GD
$image->Alpha( $c )
Alias for gdImageAlpha.
Module: PDL::IO::GD
$image->AlphaBlending( $alphaBlendingArg )
Alias for gdImageAlphaBlending.
Module: PDL::Ufunc
Return the logical and of all elements in a piddle
$x = and($data);
This routine handles bad values (see the documentation for andover). I still need to decide how to handle the case when the return value is a bad value (eg to make sure it has the same type as the input piddle OR perhaps we should die - makes sense for the conditional ops but not things like sum)
Module: PDL::Ops
Signature: (a(); b(); [o]c(); int swap)
binary and of two piddles
$c = and2 $a, $b, 0; # explicit call with trailing 0 $c = $a & $b; # overloaded call $a->inplace->and2($b,0); # modify $a inplace
It can be made to work inplace with the $a->inplace syntax.
This function is used to overload the binary & operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.
and2 does handle bad values. The state of the bad-value flag of the output piddles is unknown.
Module: PDL::Ufunc
Signature: (a(n); int+ [o]b())
Project via and to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the and along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = andover($b);
$spectrum = andover $image->xchg(0,1)
If a() contains only bad data (and its bad flag is set),
b() is set bad. Otherwise b() will have its bad flag cleared,
as it will not contain any bad values.
Module: PDL::Ufunc
Return true if any element in piddle set
Useful in conditional expressions:
if (any $a>15) { print "some values are greater than 15\n" }
See or for comments on what happens when all elements in the check are bad.
Module: PDL::Primitive
Signature: (a(n); b(m); [o] c(mn))
append two or more piddles by concatenating along their first dimensions
$a = ones(2,4,7); $b = sequence 5; $c = $a->append($b); # size of $c is now (7,4,7) (a jumbo-piddle ;)
append appends two piddles along their first dims. Rest of the dimensions
must be compatible in the threading sense. Resulting size of first dim is
the sum of the sizes of the first dims of the two argument piddles -
ie n + m.
append does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Transform
Signature: (data(); PDL::Transform t)
$out = $data->apply($t); $out = $t->apply($data);
Apply a transformation to some input coordinates.
In the example, $t is a PDL::Transform and $data is a PDL to
be interpreted as a collection of N-vectors (with index in the 0th
dimension). The output is a similar but transformed PDL.
For convenience, this is both a PDL method and a Transform method.
Module: PDL::IO::GD
Does a $im->ColorAllocate() for and entire LUT piddle at once.
The LUT piddle format is the same as for the general interface above.
Module: PDL::Image2D
Transform a set of points using a 2-D polynomial mapping
( $x, $y ) = applywarp2d( $px, $py, $u, $v )
Convert a set of points (stored in 1D piddles $u,$v)
to $x,$y using the 2-D polynomial with coefficients stored in $px
and $py. See fitwarp2d()
for more information on the format of $px and $py.
Module: PDL::Core
test for approximately equal values (relaxed ==)
# ok if all corresponding values in # piddles are within 1e-8 of each other print "ok\n" if all approx $a, $b, 1e-8;
approx is a relaxed form of the == operator and
often more appropriate for floating point types (float
and double).
Usage:
$res = approx $a, $b [, $eps]
The optional parameter $eps is remembered across invocations
and initially set to 1e-6, e.g.
approx $a, $b; # last $eps used (1e-6 initially) approx $a, $b, 1e-10; # 1e-10 approx $a, $b; # also 1e-10
Module: PDL::Doc::Perldl
Regex search PDL documentation database
apropos 'text'
perldl> apropos 'pic' rpic Read images in many formats with automatic format detection. rpiccan Test which image formats can be read/written wmpeg Write an image sequence ((x,y,n) piddle) as an MPEG animation. wpic Write images in many formats with automatic format selection. wpiccan Test which image formats can be read/written
To find all the manuals that come with PDL, try
apropos 'manual:'
and to get quick info about PDL modules say
apropos 'module:'
You get more detailed info about a PDL function/module/manual
with the help function
Module: PDL::IO::GD
$image->Arc( $cx, $cy, $w, $h, $s, $e, $color )
Alias for gdImageArc.
Module: PDL::IO::GD
$image->Arcs( $cx(pdl), $cy(pdl), $w(pdl), $h(pdl), $s(pdl), $e(pdl), $color(pdl) )
Alias for gdImageArcs.
Module: PDL::Graphics::PGPLOT::Window
Plot an arrow
Usage: arrow($x1, $y1, $x2, $y2, [, $opt]);
Plot an arrow from $x1, $y1 to $x2, $y2. The arrow shape can be
set using the option Arrow. See the documentation for general options
for details about this option (and the example below):
Example:
arrow(0, 1, 1, 2, {Arrow => {FS => 1, Angle => 1, Vent => 0.3, Size => 5}});
which draws a broad, large arrow from (0, 1) to (1, 2).
Module: PDL::Math
Signature: (a(); [o]b())
The usual trigonometric function. Works inplace.
asin does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Math
Signature: (a(); [o]b())
The standard hyperbolic function. Works inplace.
asinh does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Ops
Signature: (a(); [o]b())
Plain numerical assignment. This is used to implement the ``.='' operator
assgn does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Core
Returns a single value inside a piddle as perl scalar.
$z = at($piddle, @position); $z=$piddle->at(@position);
@position is a coordinate list, of size equal to the
number of dimensions in the piddle. Occasionally useful
in a general context, quite useful too inside PDL internals.
perldl> $x = sequence 3,4 perldl> p $x->at(1,2) 7
at converts any bad values into the string 'BAD'.
Module: PDL::Math
Signature: (a(); [o]b())
The usual trigonometric function. Works inplace.
atan does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Ops
Signature: (a(); b(); [o]c(); int swap)
elementwise atan2 of two piddles
$c = $a->atan2($b,0); # explicit function call $c = atan2 $a, $b; # overloaded use $a->inplace->atan2($b,0); # modify $a inplace
It can be made to work inplace with the $a->inplace syntax.
This function is used to overload the binary atan2 function.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.
atan2 does handle bad values. The state of the bad-value flag of the output piddles is unknown.
Module: PDL::Math
Signature: (a(); [o]b())
The standard hyperbolic function. Works inplace.
atanh does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Char
Function to fetch one string value from a PDL::Char type PDL, given a position within the PDL. The input position of the string, not a character in the string. The length of the input string is the implied first dimension.
$char = PDL::Char->new( [['abc', 'def', 'ghi'], ['jkl', 'mno', 'pqr']] ); print $char->atstr(0,1); # Prints: # jkl
Module: PDL::Graphics::TriD::Rout
Signature: (coords(nc,np);
int from(nl);
int to(nl);
strength(nl);
[o]vecs(nc,np);;
double m;
double ms;
)
Attractive potential for molecule-like constructs.
attract is used to calculate
an attractive force for many
objects, of which some attract each other (in a way
like molecular bonds).
For use by the module PDL::Graphics::TriD::MathGraph.
For definition of the potential, see the actual function.
attract does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Func
$obj->attributes; PDL::Func->attributes;
Print out the flags for the attributes of a PDL::Func object.
Useful in case the documentation is just too opaque!
PDL::Func->attributes; Flags Attribute SGR x SGR y G err
Module: PDL::Graphics::PGPLOT::Window
Usage: autolog([0|1]);
Setting the argument to 1 turns on automatic log scaling and setting it to zero turns it off again. The function can be used in both the object oriented and standard interface. To learn more, see the documentation for PDL::Graphics::PGPLOT::Window.
my $win = PDL::Graphics::PGPLOT::Window->new(dev=>'/xserve'); my $x=sequence(10); my $y=$x*$x+1;
$win->autolog(1);
$win->line($x,$y, {Axis => 'LogY'});
Module: PDL::Ufunc
Signature: (a(n); int+ [o]b())
Project via average to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the average along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = average($b);
$spectrum = average $image->xchg(0,1)
average does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Ufunc
Return the average of all elements in a piddle
$x = avg($data);
This routine handles bad values (see the documentation for average). I still need to decide how to handle the case when the return value is a bad value (eg to make sure it has the same type as the input piddle OR perhaps we should die - makes sense for the conditional ops but not things like sum)
Module: PDL::Basic
Fills a piddle with index values on Nth dimension
$z = axisvals ($piddle, $nth);
This is the routine, for which xvals, yvals etc
are mere shorthands. axisvals can be used to fill
along any dimension.
Note the 'from specification' style (see zeroes) is not available here, for obvious reasons.
Module: PDL::Primitive
Signature: ([o,nc]a(n))
Internal routine
axisvalues is the internal primitive that implements
axisvals
and alters its argument.
axisvalues does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Bad
switch on/off/examine bad data flag
if ( $a->badflag() ) {
print "Data may contain bad values.\n";
}
$a->badflag(1); # set bad data flag
$a->badflag(0); # unset bad data flag
A return value of 1 does not guarantee the presence of bad data in a piddle; all it does is say that we need to check for the presence of such beasties. To actually find out if there are any bad values present in a piddle, use the check_badflag method.
Does support bad values.
Module: PDL::Doc::Perldl
provides information on the bad-value support of a function
And has a horrible name.
badinfo 'func'
Module: PDL::Math
Signature: (a(); b(); [o]c())
Clears all infs and nans in $a to the corresponding value in $b.
badmask can be run with $a inplace:
badmask($a->inplace,0); $a->inplace->badmask(0);
If bad values are present, these are also cleared.
Module: PDL::Bad
returns the value used to indicate a missing (or bad) element
for the given piddle type. You can give it a piddle,
a PDL::Type object, or one of $PDL_B, $PDL_S, etc.
$badval = badvalue( float );
$a = ones(ushort,10);
print "The bad data value for ushort is: ",
$a->badvalue(), "\n";
If a new value is supplied via a piddle (e.g. $a->badvalue(23)),
then the data in the supplied piddle is converted to use the new
bad value as well if the data type is an integer
or $PDL::Bad::UseNaN == 0.
Currently there is no way of automatically converting the bad values of already existing piddles. This could be supported - e.g. by having a per-piddle bad value or by storing a time index in the piddle structure - if required.
If the $PDL::Bad::PerPdl flag is set then it is possible to
change the bad value on a per-piddle basis, so
$a = sequence (10);
$a->badvalue (3); $a->badflag (1);
$b = sequence (10);
$b->badvalue (4); $b->badflag (1);
will set $a to be [0 1 2 BAD 4 5 6 7 8 9] and $b to be
[0 1 2 3 BAD 5 6 7 8 9]. If the flag is not set then both
$a and $b will be set to [0 1 2 3 BAD 5 6 7 8 9]. Please
note that the code to support per-piddle bad values is
experimental in the current release.
Does support bad values.
Module: PDL::Ufunc
Return the bitwise and of all elements in a piddle
$x = band($data);
This routine handles bad values (see the documentation for bandover). I still need to decide how to handle the case when the return value is a bad value (eg to make sure it has the same type as the input piddle OR perhaps we should die - makes sense for the conditional ops but not things like sum)
Module: PDL::Ufunc
Signature: (a(n); int+ [o]b())
Project via bitwise and to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the bitwise and along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = bandover($b);
$spectrum = bandover $image->xchg(0,1)
If a() contains only bad data (and its bad flag is set),
b() is set bad. Otherwise b() will have its bad flag cleared,
as it will not contain any bad values.
Module: PDL::Core
Standard error reporting routine for PDL.
barf() is the routine PDL modules should call to report errors. This
is because barf() will report the error as coming from the correct
line in the module user's script rather than in the PDL module.
It does this magic by unwinding the stack frames until it reaches
a package NOT beginning with "PDL::". If you DO want it to report
errors in some module PDL::Foo (e.g. when debugging PDL::Foo) then
set the variable $PDL::Foo::Debugging=1.
Additionally if you set the variable $PDL::Debugging=1 you will
get a COMPLETE stack trace back up to the top level package.
Finally barf() will try and report usage information from the
PDL documentation database if the error message is of the
form 'Usage: func'.
Remember barf() is your friend. *Use* it!
At the perl level:
barf("User has too low an IQ!");
In C or XS code:
barf("You have made %d errors", count);
Note: this is one of the few functions ALWAYS exported by PDL::Core
Module: PDL::Math
Signature: (a(); [o]b())
The standard Bessel function. Works inplace.
bessj0 does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Math
Signature: (a(); [o]b())
The standard Bessel function. Works inplace.
bessj1 does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Math
Signature: (a(); int n(); [o]b())
The standard Bessel function. This has a second integer argument which gives the order of the function required. Works inplace.
bessjn does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Math
Signature: (a(); [o]b())
The standard Bessel function. Works inplace.
bessy0 does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Math
Signature: (a(); [o]b())
The standard Bessel function. Works inplace.
bessy1 does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Math
Signature: (a(); int n(); [o]b())
The standard Bessel function. This has a second integer argument which gives the order of the function required. Works inplace.
bessyn does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::IO::Dumper
Identify whether a PDL is ``big'' [Internal routine]
Internal routine takes a PDL and returns a boolean indicating whether it's small enough for direct insertion into the dump string. If 0, it can be inserted. Larger numbers yield larger scopes of PDL. 1 implies that it should be broken out but can be handled with a couple of perl commands; 2 implies full uudecode treatment.
PDLs with Astro::FITS::Header objects as headers are taken to be FITS files and are always treated as huge, regardless of size.
Module: PDL::Image2D
Signature: (I(n,m); O(q,p))
Bilinearly maps the first piddle in the second. The interpolated values are actually added to the second piddle which is supposed to be larger than the first one.
bilin2d ignores the bad-value flag of the input piddles. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Graphics::PGPLOT::Window
Plot vector as histogram (e.g. bin(hist($data)))
Usage: bin ( [$x,] $data )
Options recognised:
CENTRE - if true, the x values denote the centre of the bin
otherwise they give the lower-edge (in x) of the bin
CENTER - as CENTRE
The following standard options influence this command:
AXIS, BORDER, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH
Module: PDL::Ops
Signature: (a(); [o]b())
unary bit negation
$b = ~ $a; $a->inplace->bitnot; # modify $a inplace
It can be made to work inplace with the $a->inplace syntax.
This function is used to overload the unary ~ operator/function.
bitnot does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::IO::GD
$image->Blue( $c )
Alias for gdImageBlue.
Module: PDL::Ufunc
Return the bitwise or of all elements in a piddle
$x = bor($data);
This routine handles bad values (see the documentation for borover). I still need to decide how to handle the case when the return value is a bad value (eg to make sure it has the same type as the input piddle OR perhaps we should die - makes sense for the conditional ops but not things like sum)
Module: PDL::Ufunc
Signature: (a(n); int+ [o]b())
Project via bitwise or to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the bitwise or along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = borover($b);
$spectrum = borover $image->xchg(0,1)
If a() contains only bad data (and its bad flag is set),
b() is set bad. Otherwise b() will have its bad flag cleared,
as it will not contain any bad values.
Module: PDL::IO::GD
$image->BoundsSafe( $x, $y )
Alias for gdImageBoundsSafe.
Module: PDL::Image2D
Signature: (a(n,m); [o] b(n,m); int wx; int wy; int edgezero)
fast 2D boxcar average
$smoothim = $im->box2d($wx,$wy,$edgezero=1);
The edgezero argument controls if edge is set to zero (edgezero=1) or just keeps the original (unfiltered) values.
box2d should be updated to support similar edge options
as conv2d and med2d etc.
Boxcar averaging is a pretty crude way of filtering. For serious stuff better filters are around (e.g., use conv2d with the appropriate kernel). On the other hand it is fast and computational cost grows only approximately linearly with window size.
box2d does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::IO::Misc
Signature: (x(); )
Swaps pairs of bytes in argument x()
bswap2 does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::IO::Misc
Signature: (x(); )
Swaps quads of bytes in argument x()
bswap4 does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::IO::Misc
Signature: (x(); )
Swaps octets of bytes in argument x()
bswap8 does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Graphics::TriD::Tk
Default bindings for mousemotion with buttons 1 and 3
Module: PDL::Graphics::TriD::ButtonControl
Activates the viewport the mouse is inside when pressed
Module: PDL::Graphics::TriD::ButtonControl
A do nothing function to prevent errors if not defined in a subclass
Module: PDL::Core
Convert to byte datatype - see 'Datatype_conversions'
Module: PDL::ImageRGB
Scales a pdl into a specified data range (default 0-255)
$scale = $im->bytescl([$top])
By default $top=255, otherwise you have to give the desired top value as an
argument to bytescl. Normally bytescl doesn't rescale data that fits
already in the bounds 0..$top (it only does the type conversion if required).
If you want to force it to rescale so that the max of the output is at $top and
the min at 0 you give a negative $top value to indicate this.
Module: PDL::Complex
Signature: (a(m=2); [o]c())
complex abs() (also known as modulus)
Cabs does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); [o]c())
complex squared abs() (also known squared modulus)
Cabs2 does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
Cacos does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
Cacosh does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::CallExt
Call a function in an external library using Perl dynamic loading
callext('file.so', 'foofunc', $x, $y); # pass piddles to foofunc()
The file must be compiled with dynamic loading options
(see callext_cc). See the module docs PDL::Callext
for a description of the API.
Module: PDL::CallExt
Compile external C code for dynamic loading
Usage:
% perl -MPDL::CallExt -e callext_cc file.c -o file.so
This works portably because when Perl has built in knowledge of how to do
dynamic loading on the system on which it was installed.
See the module docs PDL::Callext for a description of
the API.
Module: PDL::Reduce
return list of valid named reduce operations
Some common operations can be accessed using a
number of names, e.g. '+', add and plus
all sum the elements along the chosen dimension.
@ops = PDL->canreduce;
This list is useful if you want to make sure which
operations can be used with reduce.
Module: PDL::Complex
Signature: (a(m=2); [o]c())
complex argument function (``angle'')
Carg does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
Casin does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
Casinh does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Core
concatentate piddles to N+1 dimensional piddle
Takes a list of N piddles of same shape as argument, returns a single piddle of dimension N+1
perldl> $x = cat ones(3,3),zeroes(3,3),rvals(3,3); p $x [ [ [1 1 1] [1 1 1] [1 1 1] ] [ [0 0 0] [0 0 0] [0 0 0] ] [ [1 1 1] [1 0 1] [1 1 1] ] ]
The output piddle is set bad if any input piddles have their bad flag set.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
Catanh does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Image2D
Signature: (a(m,n); [o]b(m,n))
Connected 8-component labeling of a binary image.
Connected 8-component labeling of 0,1 image - i.e. find seperate segmented objects and fill object pixels with object number
$segmented = cc8compt( $image > $threshold );
cc8compt ignores the bad-value flag of the input piddles. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); b(m=2); [o]c())
Complex comparison oeprator (spaceship). It orders by real first, then by imaginary. Hm, but it is mathematical nonsense! Complex numbers cannot be ordered.
Ccmp does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
complex conjugation
Cconj does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
cos (a) = 1/2 * (exp (a*i) + exp (-a*i))
Ccos does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
cosh (a) = (exp (a) + exp (-a)) / 2
Ccosh does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); b(m=2); [o]c(m=2))
complex division
Cdiv does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::FFT
Signature: (ar(); ai(); br(); bi(); [o]cr(); [o]ci())
Complex division
cdiv does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Math
Signature: (a(); [o]b())
Round to integral values in floating-point format. Works inplace.
ceil does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Image2D
Signature: (im(m,n); x(); y(); box(); [o]xcen(); [o]ycen())
Refine a list of object positions in 2D image by centroiding in a box
$box is the full-width of the box, i.e. the window
is +/- $box/2.
Bad pixels are excluded from the centroid calculation. If all elements are bad (or the pixel sum is 0 - but why would you be centroiding something with negatives in...) then the output values are set bad.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
exp (a) = exp (real (a)) * (cos (imag (a)) + i * sin (imag (a)))
Cexp does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::IO::GD
$image->Char( $f, $x, $y, $c, $color )
Alias for gdImageChar.
Module: PDL::IO::GD
$image->CharUp( $f, $x, $y, $c, $color )
Alias for gdImageCharUp.
Module: PDL::Bad
clear the bad-value flag of a piddle if it does not contain any bad values
Given a piddle whose bad flag is set, check whether it actually contains any bad values and, if not, clear the flag. It returns the final state of the bad-value flag.
print "State of bad flag == ", $pdl->check_badflag;
Does support bad values.
Module: PDL::ImageND
Smooths an image by applying circular mean. Optionally takes the center to be used.
circ_mean($im);
circ_mean($im,{Center => [10,10]});
Module: PDL::ImageND
Calculates the circular mean of an n-dim image and returns the projection. Optionally takes the center to be used.
$cmean=circ_mean_p($im);
$cmean=circ_mean_p($im,{Center => [10,10]});
Module: PDL::Graphics::PGPLOT::Window
Plot a circle on the display using the fill setting.
Usage: circle($x, $y, $radius [, $opt]);
All arguments can alternatively be given in the options hash using the following options:
The position of the center of the circle
The radius of the circle.
Module: PDL::Transform::Cartography
$a = clean_lines(t_mercator->apply(scalar(earth_coast()))); $a = clean_lines($line_pen, [threshold]); $a = $lines->clean_lines;
(Cartography) PDL method - remove projection irregularities
clean_lines massages vector data to remove jumps due to singularities
in the transform.
In the first (scalar) form, $line_pen contains both (X,Y) points and pen
values suitable to be fed to
lines:
in the second (list) form, $lines contains the (X,Y) points and $pen
contains the pen values.
clean_lines assumes that all the outline polylines are local --
that is to say, there are no large jumps. Any jumps larger than a
threshold size are broken by setting the appropriate pen values to 0.
The threshold parameter sets the relative size of the largest jump, relative
to the map range (as determined by a min/max operation). The default size is
0.1.
NOTES
This almost never catches stuff near the apex of cylindrical maps, because the anomalous vectors get arbitrarily small. This could be improved somewhat by looking at individual runs of the pen and using a relative length scale that is calibrated to the rest of each run. it is probably not worth the computational overhead.
Module: PDL::Primitive
Clip (threshold) a piddle by (optional) upper or lower bounds.
$b = $a->clip(0,3); $c = $a->clip(undef, $x);
clip handles bad values since it is just a wrapper around hclip and lclip.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
log (a) = log (cabs (a)) + i * carg (a)
Clog does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Graphics::PGPLOT::Window
Close a plot window
Usage: $win->close()
Close the current window. This does not necessarily mean that the window is removed from your screen, but it does ensure that the device is closed.
A message will be printed to STDOUT giving the name of the
file created if the plot was made to a hardcopy device and
$PDL::verbose is true.
Module: PDL::Graphics::PGPLOT
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 is deleted and focus is
transferred to the lowest numbered window in existence. If many windows
have been created and deleted this might not be what you expect, so
it is recommended to make an explicit call to focus_window after
any call to close_window.
Module: PDL::Core
``clumps'' several dimensions into one large dimension
If called with one argument $n clumps the first $n
dimensions into one. For example, if $a has dimensions
(5,3,4) then after
$b = $a->clump(2); # Clump 2 first dimensions
the variable $b will have dimensions (15,4)
and the element $b->at(7,3) refers to the element
$a->at(1,2,3).
Use clump(-1) to flatten a piddle. The method flat
is provided as a convenient alias.
Clumping with a negative dimension in general leaves that many
dimensions behind -- e.g. clump(-2) clumps all of the first few
dimensions into a single one, leaving a 2-D piddle.
If clump is called with an index list with more than one element
it is treated as a list of dimensions that should be clumped together
into one. The resulting
clumped dim is placed at the position of the lowest index in the list.
This convention ensures that clump does the expected thing in
the usual cases. The following example demonstrates typical usage:
$a = sequence 2,3,3,3,5; # 5D piddle $c = $a->clump(1..3); # clump all the dims 1 to 3 into one print $c->info; # resulting 3D piddle has clumped dim at pos 1 PDL: Double D [2,27,5]
Module: PDL::Complex
Signature: (a(m=2); b(m=2); [o]c(m=2))
complex multiplication
Cmul does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::FFT
Signature: (ar(); ai(); br(); bi(); [o]cr(); [o]ci())
Complex multiplication
cmul does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Graphics::TriD::Contours
A simple colortable function for use with the set_colortable function.
coldhot_colortable defines a blue red spectrum of colors where the smallest contour value is blue, the highest is red and the others are shades in between.
Module: PDL::IO::GD
$image->ColorAllocate( $r, $g, $b )
Alias for gdImageColorAllocate.
Module: PDL::IO::GD
$image->ColorAllocateAlpha( $r, $g, $b, $a )
Alias for gdImageColorAllocateAlpha.
Module: PDL::IO::GD
$image->ColorAllocateAlphas( $r(pdl), $g(pdl), $b(pdl), $a(pdl) )
Alias for gdImageColorAllocateAlphas.
Module: PDL::IO::GD
$image->ColorAllocates( $r(pdl), $g(pdl), $b(pdl) )
Alias for gdImageColorAllocates.
Module: PDL::IO::GD
$image->ColorClosest( $r, $g, $b )
Alias for gdImageColorClosest.
Module: PDL::IO::GD
$image->ColorClosestAlpha( $r, $g, $b, $a )
Alias for gdImageColorClosestAlpha.
Module: PDL::IO::GD
$image->ColorClosestHWB( $r, $g, $b )
Alias for gdImageColorClosestHWB.
Module: PDL::IO::GD
$image->ColorDeallocate( $color )
Alias for gdImageColorDeallocate.
Module: PDL::IO::GD
$image->ColorExact( $r, $g, $b )
Alias for gdImageColorExact.
Module: PDL::IO::GD
$image->ColorExactAlpha( $r, $g, $b, $a )
Alias for gdImageColorExactAlpha.
Module: PDL::IO::GD
$image->ColorResolve( $r, $g, $b )
Alias for gdImageColorResolve.
Module: PDL::IO::GD
$image->ColorResolveAlpha( $r, $g, $b, $a )
Alias for gdImageColorResolveAlpha.
Module: PDL::IO::GD
$image->ColorsTotal( )
Alias for gdImageColorsTotal.
Module: PDL::IO::GD
$image->ColorTransparent( $color )
Alias for gdImageColorTransparent.
Module: PDL::Graphics::TriD::Rout
Signature: (x(); y(); z();
float [o]coords(tri=3);)
Combine three coordinates into a single piddle.
Combine x, y and z to a single piddle the first dimension of which is 3. This routine does dataflow automatically.
combcoords does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Graphics::PGPLOT::Window
Display image as contour map
Usage: cont ( $image, [$contours, $transform, $misval], [$opt] )
Notes: $transform for image/cont etc. is used in the same way as the
TR() array in the underlying PGPLOT FORTRAN routine but is,
fortunately, zero-offset. The transform() routine can be used to
create this piddle.
Options recognised:
CONTOURS - A piddle with the contour levels
FOLLOW - Follow the contour lines around (uses pgcont rather than
pgcons) If this is set >0 the chosen linestyle will be
ignored and solid line used for the positive contours
and dashed line for the negative contours.
LABELS - An array of strings with labels for each contour
LABELCOLOUR - The colour of labels if different from the draw colour
This will not interfere with the setting of draw colour
using the colour keyword.
MISSING - The value to ignore for contouring
NCONTOURS - The number of contours wanted for automatical creation,
overridden by CONTOURS
TRANSFORM - The pixel-to-world coordinate transform vector
The following standard options influence this command:
AXIS, BORDER, COLOUR, LINESTYLE, LINEWIDTH, JUSTIFY, SCALE, PIX, PITCH, ALIGN
$x=sequence(10,10);
$ncont = 4;
$labels= ['COLD', 'COLDER', 'FREEZING', 'NORWAY']
# This will give four blue contour lines labelled in red.
cont $x, {NCONT => $ncont, LABELS => $labels, LABELCOLOR => RED,
COLOR => BLUE}
Module: PDL::Graphics::TriD::Rout
This is the interface for the pp routine contour_segments_internal - it takes 3 piddles as input
$c is a contour value (or a list of contour values)
$data is an [m,n] array of values at each point
$points is a list of [3,m,n] points, it should be a grid
monotonically increasing with m and n.
contour_segments returns a reference to a Perl array of
line segments associated with each value of $c. It does not (yet) handle
missing data values.
The data array represents samples of some field observed on the surface described
by points. For each contour value we look for intersections on the line segments
joining points of the data. When an intersection is found we look to the adjoining
line segments for the other end(s) of the line segment(s). So suppose we find an
intersection on an x-segment. We first look down to the left y-segment, then to the
right y-segment and finally across to the next x-segment. Once we find one in a
box (two on a point) we can quit because there can only be one. After we are done
with a given x-segment, we look to the leftover possibilities for the adjoining y-segment.
Thus the contours are built as a collection of line segments rather than a set of closed
polygons.
Module: PDL::Primitive
Signature: (a(m); kern(p); [o]b(m); int reflect)
1d convolution along first dimension
$con = conv1d sequence(10), pdl(-1,0,1), {Boundary => 'reflect'};
By default, periodic boundary conditions are assumed (i.e. wrap around).
Alternatively, you can request reflective boundary conditions using
the Boundary option:
{Boundary => 'reflect'} # case in 'reflect' doesn't matter
The convolution is performed along the first dimension. To apply it across another dimension use the slicing routines, e.g.
$b = $a->mv(2,0)->conv1d($kernel)->mv(0,2); # along third dim
This function is useful for threaded filtering of 1D signals.
Compare also conv2d, convolve, fftconvolve, fftwconv, rfftwconv
conv1d does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Image2D
Signature: (a(m,n); kern(p,q); [o]b(m,n); int opt)
2D convolution of an array with a kernel (smoothing)
For large kernels, using a FFT routine,
such as fftconvolve() in PDL::FFT,
will be quicker.
$new = conv2d $old, $kernel, {OPTIONS}
$smoothed = conv2d $image, ones(3,3), {Boundary => Reflect}
Boundary - controls what values are assumed for the image when kernel
crosses its edge:
=> Default - periodic boundary conditions
(i.e. wrap around axis)
=> Reflect - reflect at boundary
=> Truncate - truncate at boundary
Unlike the FFT routines, conv2d is able to process bad values.
Module: PDL::Core
Generic datatype conversion function
$y = convert($x, $newtype);
$y = convert $x, long $y = convert $x, ushort
$newtype is a type number, for convenience they are
returned by long() etc when called without arguments.
Module: PDL::FFT
Signature: ([o,nc]a(m); [o,nc]b(m))
Internal routine doing maths for convolution
convmath does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::ImageND
Signature: (a(m); b(n); int adims(p); int bdims(q); [o]c(m))
N-dimensional convolution (Deprecated; use convolveND)
$new = convolve $a, $kernel
Convolve an array with a kernel, both of which are N-dimensional. This routine does direct convolution (by copying) but uses quasi-periodic boundary conditions: each dim ``wraps around'' to the next higher row in the next dim.
This routine is kept for backwards compatibility with earlier scripts; for most purposes you want convolveND instead: it runs faster and handles a variety of boundary conditions.
convolve does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::ImageND
Signature: (k0(); SV *k; SV *aa; SV *a)
Speed-optimized convolution with selectable boundary conditions
$new = convolveND($a, $kernel, [ {options} ]);
Conolve an array with a kernel, both of which are N-dimensional.
If the kernel has fewer dimensions than the array, then the extra array dimensions are threaded over. There are options that control the boundary conditions and method used.
The kernel's origin is taken to be at the kernel's center. If your kernel has a dimension of even order then the origin's coordinates get rounded up to the next higher pixel (e.g. (1,2) for a 3x4 kernel). This mimics the behavior of the earlier convolve and fftconvolve routines, so convolveND is a drop-in replacement for them.
The kernel may be any size compared to the image, in any dimension.
The kernel and the array are not quite interchangeable (as in mathematical convolution): the code is inplace-aware only for the array itself, and the only allowed boundary condition on the kernel is truncation.
convolveND is inplace-aware: say convolveND(inplace $a ,$k) to modify
a variable in-place. You don't reduce the working memory that way -- only
the final memory.
OPTIONS
Options are parsed by PDL::Options, so unique abbreviations are accepted.
The boundary condition on the array, which affects any pixel closer to the edge than the half-width of the kernel.
The boundary conditions are the same as those accepted by range, because this option is passed directly into range. Useful options are 'truncate' (the default), 'extend', and 'periodic'. You can select different boundary conditions for different axes -- see range for more detail.
The (default) truncate option marks all the near-boundary pixels as BAD if you have bad values compiled into your PDL.
The method to use for the convolution. Acceptable alternatives are 'direct', 'fft', or 'auto'. The direct method is an explicit copy-and-multiply operation; the fft method takes the Fourier transform of the input and output kernels. The two methods give the same answer to within double-precision numerical roundoff. The fft method is much faster for large kernels; the direct method is faster for tiny kernels. The tradeoff occurs when the array has about 400x more pixels than the kernel.
The default method is 'auto', which chooses direct or fft convolution based on the size of the input arrays.
NOTES
At the moment there's no way to thread over kernels. That could/should be fixed.
The threading over input is cheesy and should probably be fixed: currently the kernel just gets dummy dimensions added to it to match the input dims. That does the right thing tersely but probably runs slower than a dedicated threadloop.
The direct copying code uses PP primarily for the generic typing: it includes its own threadloops.
convolveND does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Core
Make a physical copy of a piddle
$new = $old->copy;
Since $new = $old just makes a new reference, the
copy method is provided to allow real independent
copies to be made.
Module: PDL::Bad
Signature: (a(); mask(); [o]b())
Copies values from one piddle to another, setting them bad if they are bad in the supplied mask.
Can be done inplace.
$a = byte( [0,1,3] ); $mask = byte( [0,0,0] ); set($mask,1,$mask->badvalue); $a->inplace->copybad( $mask ); p $a; [0 BAD 3]
It is equivalent to:
$c = $a + $mask * 0
Handles bad values.
Module: PDL::IO::GD
$image->CopyRotated( $dstX, $dstY, $srcX, $srcY, $srcWidth, $srcHeight, $angle )
Alias for gdImageCopyRotated.
Module: PDL::Ops
Signature: (a(); [o]b())
the cos function
$b = cos $a; $a->inplace->cos; # modify $a inplace
It can be made to work inplace with the $a->inplace syntax.
This function is used to overload the unary cos operator/function.
cos does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Math
Signature: (a(); [o]b())
The standard hyperbolic function. Works inplace.
cosh does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (r(m=2); [o]p(m=2))
convert complex numbers in polar (mod,arg) form to rectangular form
Cp2r does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); b(m=2); [o]c(m=2))
complex pow() (**-operator)
Cpow does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2,n); [o]c(m=2))
Project via product to N-1 dimension
Cprodover does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
compute the projection of a complex number to the riemann sphere
Cproj does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::ImageRGB
quantize and reduce colours in 8-bit images
($out, $lut) = cquant($image [,$ncols]);
This function does color reduction for <=8bit displays and accepts 8bit RGB and 8bit palette images. It does this through an interface to the ppm_quant routine from the pbmplus package that implements the median cut routine which intellegently selects the 'best' colors to represent your image on a <= 8bit display (based on the median cut algorithm). Optional args: $ncols sets the maximum nunmber of colours used for the output image (defaults to 256). There are images where a different color reduction scheme gives better results (it seems this is true for images containing large areas with very smoothly changing colours).
Returns a list containing the new palette image (type PDL_Byte) and the RGB colormap.
Module: PDL::Complex
Signature: (r(m=2); float+ [o]p(m=2))
convert complex numbers in rectangular form to polar (mod,arg) form
Cr2p does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2,n); int n => n)
Compute the n roots of a. n must be a positive integer. The result will always be a complex type!
Croots does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Primitive
Signature: (a(tri=3); b(tri); [o] c(tri))
Cross product of two 3D vectors
After
$c = crossp $a, $b
the inner product $c*$a and $c*$b will be zero, i.e. $c is
orthogonal to $a and $b
crossp does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); b(); [o]c(m=2))
mixed complex/real multiplication
Cscale does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
sin (a) = 1/(2*i) * (exp (a*i) - exp (-a*i))
Csin does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
sinh (a) = (exp (a) - exp (-a)) / 2
Csinh does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
Csqrt does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Graphics::PGPLOT::Window
Load an image colour table.
Usage:
ctab ( $name, [$contrast, $brightness] ) # Builtin col table ctab ( $ctab, [$contrast, $brightness] ) # $ctab is Nx4 array ctab ( $levels, $red, $green, $blue, [$contrast, $brightness] ) ctab ( '', $contrast, $brightness ) # use last color table
Note: See PDL::Graphics::LUT for access to a large number of colour tables.
Notionally, all non-RGB images and vectors have their colors looked up in the window's color table. Colors in images and such are scaled to a normalized pseudocolor domain on the line segment [0,1]; the color table is a piecewise linear function that maps this one-dimensional scale to the three-dimensional normalized RGB color space [0,1]^3.
You can specify specific indexed colors by appropriate use of the (levels,red,green,blue) syntax -- but that is deprecated, since the actual available number of colors can change depending on the output device. (Someone needs to write a specific hardware-dependent lookup table interface).
See also imag for a description of how to use only part of the color table for a particular image.
Module: PDL::Graphics::PGPLOT::Window
Return information about the currently loaded color table
Module: PDL::Complex
Signature: (a(m=2); [o]c(m=2))
Ctanh does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Ufunc
Signature: (a(n); int+ [o]b(n))
Cumulative product
This function calculates the cumulative product along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
The sum is started so that the first element in the cumulative product is the first element of the parameter.
$a = cumuprodover($b);
$spectrum = cumuprodover $image->xchg(0,1)
cumuprodover does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Ufunc
Signature: (a(n); int+ [o]b(n))
Cumulative sum
This function calculates the cumulative sum along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
The sum is started so that the first element in the cumulative sum is the first element of the parameter.
$a = cumusumover($b);
$spectrum = cumusumover $image->xchg(0,1)
cumusumover does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Graphics::PGPLOT::Window
Interactively read cursor positions.
Usage: ($x, $y, $ch, $xref, $yref) = cursor($opt)
This routine has no standard input parameters, but the type of cursor
can be set by setting the option Type as a key in the anonymous hash
$opt. The first three return values from the function are always
defined and gives the position selected by the user and the character
pressed.
Depending on the cursor type selected the last two arguments might also
be defined and these give a reference position. For instance if the cursor
is selected to be Rectangle then the reference position gives one of
the corners of the rectangle and $x and $y the diagonally opposite
one.
Options recognised:
The reference position to be used
The type of cursor. This can be selected using a number between 0 and 7 as
in PGPLOT, or alternatively you can specify these as, Default (0),
RadialLine (1), Rectangle (2), TwoHorizontalLines (3),
TwoVerticalLines (4), HorizontalLine (5), VerticalLine (6)
and CrossHair (7) respectively. The default cursor is just the normal
mouse cursor.
For the RadialLine you must specify the reference point, whereas for
the Two(Vertical|Horizontal)Lines cursor the X or Y reference point,
respectively, must be specified.
To select a region on a plot, use the rectangle cursor:
($x, $y, $ch, $xref, $yref) = cursor({Type => 'Rectangle'});
poly pdl($x, $xref, $xref, $x, $x), pdl($y, $y, $yref, $yref, $y);
To select a region of the X-axis:
($x1, $y1, $ch) = cursor({Type => 'VerticalLine'});
($x2, $y2, $ch) = cursor({Type => 'TwoVerticalLines', XRef => $x1});
Module: PDL::IO::GD
$image->DashedLine( $x1, $y1, $x2, $y2, $color )
Alias for gdImageDashedLine.
Module: PDL::IO::GD
$image->DashedLines( $x1(pdl), $y1(pdl), $x2(pdl), $y2(pdl), $color(pdl) )
Alias for gdImageDashedLines.
Module: PDL::Core
byte|short|ushort|long|longlong|float|double convert shorthands
$y = double $x; $y = ushort [1..10]; # all of byte|short|ushort|long|float|double behave similarly
When called with a piddle argument, they convert to the specific datatype.
When called with a numeric or list / listref argument they construct
a new piddle. This is a convenience to avoid having to be
long-winded and say $x = long(pdl(42))
Thus one can say:
$a = float(1,2,3,4); # 1D $a = float([1,2,3],[4,5,6]); # 2D $a = float([[1,2,3],[4,5,6]]); # 2D
Note the last two are equivalent - a list is automatically
converted to a list reference for syntactic convenience. i.e. you
can omit the outer []
When called with no arguments return a special type token. This allows syntactical sugar like:
$x = ones byte, 1000,1000;
This example creates a large piddle directly as byte datatype in order to save memory.
In order to control how undefs are handled in converting from perl lists to
PDLs, one can set the variable $PDL::undefval;
see the function pdl() for more details.
perldl> p $x=sqrt float [1..10] [1 1.41421 1.73205 2 2.23607 2.44949 2.64575 2.82843 3 3.16228] perldl> p byte $x [1 1 1 2 2 2 2 2 3 3]
Module: PDL::Ufunc
Signature: (a(n); double [o]b())
Project via average to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the average along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = daverage($b);
$spectrum = daverage $image->xchg(0,1)
Unlike average, the calculation is performed in double precision.
daverage does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Ufunc
Return the average (in double precision) of all elements in a piddle
$x = davg($data);
This routine handles bad values (see the documentation for daverage). I still need to decide how to handle the case when the return value is a bad value (eg to make sure it has the same type as the input piddle OR perhaps we should die - makes sense for the conditional ops but not things like sum)
Module: PDL::Ufunc
Signature: (a(n); double [o]b(n))
Cumulative product
This function calculates the cumulative product along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
The sum is started so that the first element in the cumulative product is the first element of the parameter.
$a = cumuprodover($b);
$spectrum = cumuprodover $image->xchg(0,1)
Unlike cumuprodover, the calculations are performed in double precision.
dcumuprodover does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Ufunc
Signature: (a(n); double [o]b(n))
Cumulative sum
This function calculates the cumulative sum along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
The sum is started so that the first element in the cumulative sum is the first element of the parameter.
$a = cumusumover($b);
$spectrum = cumusumover $image->xchg(0,1)
Unlike cumusumover, the calculations are performed in double precision.
dcumusumover does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::IO::Dumper
Convenience function copies a complete perl data structure by the brute force method of ``eval sdump''.
Module: PDL::Graphics::OpenGL
default options for object oriented methods
Module: PDL::GSL::INTERP
The deriv function returns the derivative of the interpolating function at a given point. By default it will barf if you try to extrapolate, to comply silently if the point to be evaluated is out of range pass the option {Extrapolate => 1}
Usage:
$result = $spl->deriv($points,$opt);
Example:
my $res = $spl->deriv($x)
$res = $spl->deriv($x,{Extrapolate => 0}) #same as above
# silently comply if $x is out of range
$res = $spl->deriv($x,{Extrapolate => 1})
Module: PDL::GSL::INTERP
The deriv2 function returns the second derivative of the interpolating function at a given point. By default it will barf if you try to extrapolate, to comply silently if the point to be evaluated is out of range pass the option {Extrapolate => 1}
Usage:
$result = $spl->deriv2($points,$opt);
Example:
my $res = $spl->deriv2($x)
$res = $spl->deriv2($x,{Extrapolate => 0}) #same as above
# silently comply if $x is out of range
$res = $spl->deriv2($x,{Extrapolate => 1})
Module: PDL::DiskCache
This is the perl hook for object destruction. It just makes a call to ``sync'', to flush the cache out to disk. Destructor calls from perl don't happen at a guaranteed time, so be sure to call ``sync'' if you need to ensure that the files get flushed out, e.g. to use 'em somewhere else.
Module: PDL::IO::GD
$image->Destroy( )
Alias for gdImageDestroy.
Module: PDL::MatrixOps
Signature: (a(m,m); sv opt)
$det = det($a,{opt});
Determinant of a square matrix using LU decomposition (for large matrices)
You feed in a square matrix, you get back the determinant. Some options exist that allow you to cache the LU decomposition of the matrix (note that the LU decomposition is invalid if the determinant is zero!). The LU decomposition is cacheable, in case you want to re-use it. This method of determinant finding is more rapid than recursive-descent on large matrices, and if you reuse the LU decomposition it's essentially free.
If you ask det to thread (by giving it a 3-D or higher dim piddle) then lu_decomp drops you through to lu_decomp2, which is numerically unstable (and hence not useful for very large matrices) but quite fast.
If you want to use threading on a matrix that's less than, say, 10x10, and might be near singular, then you might want to use determinant, which is a more robust (but slower) determinant finder, instead.
OPTIONS:
Provides a cache for the LU decomposition of the matrix. If you provide the key but leave the value undefined, then the LU decomposition goes in here; if you put an LU decomposition here, it will be used and the matrix will not be decomposed again.
Module: PDL::Matrix
returns a generalized determinant of a matrix. If the matrix is not
regular, one can specify the rank of the matrix and the corresponding
subdeterminant is returned. This is implemented using the eigens
function.
print msequence(3,3)->determinant(2) # determinant of
# regular 2x2 submatrix
-24
Module: PDL::MatrixOps
Signature: (a(m,m))
$det = determinant($a);
Determinant of a square matrix, using recursive descent (threadable).
This is the traditional, robust recursive determinant method taught in
most linear algebra courses. It scales like O(n!) (and hence is
pitifully slow for large matrices) but is very robust because no
division is involved (hence no division-by-zero errors for singular
matrices). It's also threadable, so you can find the determinants of
a large collection of matrices all at once if you want.
Matrices up to 3x3 are handled by direct multiplication; larger matrices are handled by recursive descent to the 3x3 case.
The LU-decomposition method det is faster in isolation for single matrices larger than about 4x4, and is much faster if you end up reusing the LU decomposition of $a, but does not thread well.
Module: PDL::Graphics::PGPLOT
Open PGPLOT graphics device
Usage: dev $device, [$nx,$ny, $opt];
$device is a PGPLOT graphics device such as ``/xserve'' or ``/ps'',
if omitted defaults to last used device (or value of env
var PGPLOT_DEV if first time).
$nx, $ny specify sub-panelling. The function returns the id of
the newly created window - this can subsequently be used as argument to
focus_window to select the window.
The result of this command can be modified using options. The options
recognised are the same as for new_window - which primarily and in
addition it is possible to set the default values for a window that are
defined in the PDL::PGPLOTOptions manpage, see this for details but see below for
a synopsis.
In addition dev recognises the option NewWindow which allows the
user to specify that a dev command is to create a new window rather than
closing the previous. This allows a large number of output destinations to
be open at the same time, which occasionally can be convenient.
Here is a quick summary of the most useful additional options that can be given:
Alternative to $device.
The aspect ratio of the output window
The width of the plot window in inches
The axis colour to be used as default for plots in this window. In the same
way it is possible to set the default character size (CharSize) and axis
and box styles. See the PDL::Graphics::PGPLOTOptions manpage for details.
The name of a window. This name can subsequently be used to refer to the window instead of its ID, making interactive use somewhat more intuitive.
To open a X-window output that will stay 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});
Module: PDL::Graphics::PGPLOT::Window
This function returns the device type of the present window.
Module: PDL::Core
Returns the multidimensional diagonal over the specified dimensions.
$d = $x->diagonal(dim1, dim2,...)
perldl> $a = zeroes(3,3,3); perldl> ($b = $a->diagonal(0,1))++; perldl> p $a [ [ [1 0 0] [0 1 0] [0 0 1] ] [ [1 0 0] [0 1 0] [0 0 1] ] [ [1 0 0] [0 1 0] [0 0 1] ] ]
Module: PDL::Slices
Signature: (P(); C(); SV *list)
Returns the multidimensional diagonal over the specified dimensions.
The diagonal is placed at the first (by number) dimension that is
diagonalized.
The other diagonalized dimensions are removed. So if $a has dimensions
(5,3,5,4,6,5) then after
$b = $a->diagonal(0,2,5);
the piddle $b has dimensions (5,3,4,6) and
$b->at(2,1,0,1) refers
to $a->at(2,1,2,0,1,2).
NOTE: diagonal doesn't handle threadids correctly. XXX FIX
diagonalI does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Slices
Dice rows/columns/planes out of a PDL using indexes for each dimension.
This function can be used to extract irregular subsets along many dimension of a PDL, e.g. only certain rows in an image, or planes in a cube. This can of course be done with the usual dimension tricks but this saves having to figure it out each time!
This method is similar in functionality to the slice
method, but slice requires that contiguous ranges or ranges
with constant offset be extracted. ( i.e. slice requires
ranges of the form 1,2,3,4,5 or 2,4,6,8,10). Because of this
restriction, slice is more memory efficient and slightly faster
than dice
$slice = $data->dice([0,2,6],[2,1,6]); # Dicing a 2-D array
The arguments to dice are arrays (or 1D PDLs) for each dimension
in the PDL. These arrays are used as indexes to which rows/columns/cubes,etc
to dice-out (or extract) from the $data PDL.
Use X to select all indices along a given dimension (compare also
mslice). As usual (in slicing methods) trailing
dimensions can be omitted implying X'es for those.
perldl> $a = sequence(10,4) perldl> p $a [ [ 0 1 2 3 4 5 6 7 8 9] [10 11 12 13 14 15 16 17 18 19] [20 21 22 23 24 25 26 27 28 29] [30 31 32 33 34 35 36 37 38 39] ] perldl> p $a->dice([1,2],[0,3]) # Select columns 1,2 and rows 0,3 [ [ 1 2] [31 32] ] perldl> p $a->dice(X,[0,3]) [ [ 0 1 2 3 4 5 6 7 8 9] [30 31 32 33 34 35 36 37 38 39] ] perldl> p $a->dice([0,2,5]) [ [ 0 2 5] [10 12 15] [20 22 25] [30 32 35] ]
As this is an index function, any modifications to the
slice change the parent (use the .= operator).
Module: PDL::Slices
Dice rows/columns/planes from a single PDL axis (dimension) using index along a specified axis
This function can be used to extract irregular subsets along any dimension, e.g. only certain rows in an image, or planes in a cube. This can of course be done with the usual dimension tricks but this saves having to figure it out each time!
$slice = $data->dice_axis($axis,$index);
perldl> $a = sequence(10,4) perldl> $idx = pdl(1,2) perldl> p $a->dice_axis(0,$idx) # Select columns [ [ 1 2] [11 12] [21 22] [31 32] ] perldl> $t = $a->dice_axis(1,$idx) # Select rows perldl> $t.=0 perldl> p $a [ [ 0 1 2 3 4 5 6 7 8 9] [ 0 0 0 0 0 0 0 0 0 0] [ 0 0 0 0 0 0 0 0 0 0] [30 31 32 33 34 35 36 37 38 39] ]
The trick to using this is that the index selects
elements along the dimensions specified, so if you
have a 2D image axis=0 will select certain X values
- i.e. extract columns
As this is an index function, any modifications to the slice change the parent.
Module: PDL::GSL::DIFF
Signature: (double x(); double [o] res(); double [o] abserr(); SV* funcion)
info not available
diff_backward does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::GSL::DIFF
Signature: (double x(); double [o] res(); double [o] abserr(); SV* funcion)
info not available
diff_central does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::GSL::DIFF
Signature: (double x(); double [o] res(); double [o] abserr(); SV* funcion)
info not available
diff_forward does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Core
Returns the size of the given dimension of a piddle. Alias for getdim.
Module: PDL::Core
Return piddle dimensions as a perl list
@dims = $piddle->dims; @dims = dims($piddle);
perldl> p @tmp = dims zeroes 10,3,22 10 3 22
Module: PDL::DiskCache
Object constructor.
$a = diskcache(\@f,\%options);
see the TIEARRAY options,below.
Module: PDL::Ops
Signature: (a(); b(); [o]c(); int swap)
divide two piddles
$c = divide $a, $b, 0; # explicit call with trailing 0 $c = $a / $b; # overloaded call $a->inplace->divide($b,0); # modify $a inplace
It can be made to work inplace with the $a->inplace syntax.
This function is used to overload the binary / operator.
Note that when calling this function explicitly you need to supply
a third argument that should generally be zero (see first example).
This restriction is expected to go away in future releases.
divide does handle bad values. The state of the bad-value flag of the output piddles is unknown.
Module: PDL::Core
Turn on/off dataflow
$x->doflow; doflow($x);
Module: PDL::Core
Opposite of 'cat' :). Split N dim piddle to list of N-1 dim piddles
Takes a single N-dimensional piddle and splits it into a list of N-1 dimensional piddles. The breakup is done along the last dimension. Note the dataflown connection is still preserved by default, e.g.:
perldl> $p = ones 3,3,3 perldl> ($a,$b,$c) = dog $p perldl> $b++; p $p [ [ [1 1 1] [1 1 1] [1 1 1] ] [ [2 2 2] [2 2 2] [2 2 2] ] [ [1 1 1] [1 1 1] [1 1 1] ] ]
Break => 1 Break dataflow connection (new copy)
The output piddles are set bad if the original piddle has its bad flag set.
Module: PDL::Core
Convert to double datatype - see 'Datatype_conversions'
Module: PDL::Ufunc
Return the product (in double precision) of all elements in a piddle
$x = dprod($data);
This routine handles bad values (see the documentation for dprodover). I still need to decide how to handle the case when the return value is a bad value (eg to make sure it has the same type as the input piddle OR perhaps we should die - makes sense for the conditional ops but not things like sum)
Module: PDL::Ufunc
Signature: (a(n); double [o]b())
Project via product to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the product along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = dprodover($b);
$spectrum = dprodover $image->xchg(0,1)
Unlike prodover, the calculations are performed in double precision.
dprodover does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Graphics::PGPLOT::Window
Add a wedge (colour bar) to an image.
$win->draw_wedge( [$opt] )
Adds a wedge - shows the mapping between colour and value for a pixel - to
the current image. This can also be achieved by setting DrawWedge to 1
when calling the imag routine.
The colour and font size are the same as used to draw the image axes
(although this will probably fail if you did it yourself). To control the size
and location of the wedge, use the Wedge option, giving it a hash reference
containing any of the following:
Which side of the image to draw the wedge: can be one of 'B', 'L', 'T', or 'R'. Default is 'R'.
How far from the egde of the image should the wedge be drawn, in units of character size. To draw within the image use a negative value. Default is 1.5.
How wide should the wedge be, in units of character size. Default is 2.
A text label to be added to the wedge. If set, it is probably worth
increasing the Width value by about 1 to keep the text readable.
Default is ''. This is equivalent to the WTitle option to
imag, fits_imag, and similar methods.
The pixel value corresponding to the ``maximum'' colour. If undef, uses the
value used by imag (recommended choice). Default is undef.
The pixel value corresponding to the ``minimum'' colour. If undef, uses the
value used by imag (recommended choice). Default is undef.
$a = rvals(50,50);
$win = PDL::Graphics::PGPLOT::Window->new();
$win->imag( $a, { Justify => 1, ITF => 'sqrt' } );
$win->draw_wedge( { Wedge => { Width => 4, Label => 'foo' } } );
# although the following might be more sensible
$win->imag( $a, { Justify => 1, ITF => 'sqrt', DrawWedge => 1,
Wedge => { Width => 4, Label => 'foo'} } );
Module: PDL::Ufunc
Return the sum (in double precision) of all elements in a piddle
$x = dsum($data);
This routine handles bad values (see the documentation for dsumover). I still need to decide how to handle the case when the return value is a bad value (eg to make sure it has the same type as the input piddle OR perhaps we should die - makes sense for the conditional ops but not things like sum)
Module: PDL::Ufunc
Signature: (a(n); double [o]b())
Project via sum to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the sum along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = dsumover($b);
$spectrum = dsumover $image->xchg(0,1)
Unlike sumover, the calculations are performed in double precision.
dsumover does handle bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Module: PDL::Core
Insert a 'dummy dimension' of given length (defaults to 1)
No relation to the 'Dungeon Dimensions' in Discworld!
Negative positions specify relative to last dimension,
i.e. dummy(-1) appends one dimension at end,
dummy(-2) inserts a dummy dimension in front of the
last dim, etc.
If you specify a dimension position larger than the existing
dimension list of your PDL, the PDL gets automagically padded with extra
dummy dimensions so that you get the dim you asked for, in the slot you
asked for. This could cause you trouble if, for example,
you ask for $a->dummy(5000,1) because $a will get 5,000 dimensions,
each of rank 1.
Because padding at the beginning of the dimension list moves existing dimensions from slot to slot, it's considered unsafe, so automagic padding doesn't work for large negative indices -- only for large positive indices.
$y = $x->dummy($position[,$dimsize]);
perldl> p sequence(3)->dummy(0,3) [ [0 0 0] [1 1 1]