{"id":20011284,"url":"https://github.com/pdlporters/pdl-graphics-simple","last_synced_at":"2025-09-12T08:37:56.005Z","repository":{"id":7027081,"uuid":"8300203","full_name":"PDLPorters/PDL-Graphics-Simple","owner":"PDLPorters","description":"This is an interface layer to the several PDL::Graphics modules out there.  It is intended to become part of the PDL core.","archived":false,"fork":false,"pushed_at":"2025-01-16T17:03:29.000Z","size":437,"stargazers_count":5,"open_issues_count":2,"forks_count":5,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-06-22T13:07:58.787Z","etag":null,"topics":["gnuplot","pdl","perl","pgplot","plotting","plplot","prima"],"latest_commit_sha":null,"homepage":"https://p3rl.org/PDL::Graphics::Simple","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PDLPorters.png","metadata":{"files":{"readme":"README.pod","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2013-02-19T21:45:37.000Z","updated_at":"2025-01-16T17:03:31.000Z","dependencies_parsed_at":"2024-10-28T04:37:53.482Z","dependency_job_id":"5a83a140-0ad1-44a5-9533-ce9f4dcf9aad","html_url":"https://github.com/PDLPorters/PDL-Graphics-Simple","commit_stats":{"total_commits":151,"total_committers":11,"mean_commits":"13.727272727272727","dds":0.4768211920529801,"last_synced_commit":"14ccd9752ca0abf4b8884d9bbead0cdf1265d2fd"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/PDLPorters/PDL-Graphics-Simple","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDLPorters%2FPDL-Graphics-Simple","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDLPorters%2FPDL-Graphics-Simple/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDLPorters%2FPDL-Graphics-Simple/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDLPorters%2FPDL-Graphics-Simple/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PDLPorters","download_url":"https://codeload.github.com/PDLPorters/PDL-Graphics-Simple/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDLPorters%2FPDL-Graphics-Simple/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261296938,"owners_count":23137220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gnuplot","pdl","perl","pgplot","plotting","plplot","prima"],"created_at":"2024-11-13T07:25:08.952Z","updated_at":"2025-06-22T13:07:59.236Z","avatar_url":"https://github.com/PDLPorters.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"=head1 OVERVIEW\n\nPDL::Graphics::Simple is a unified plotting interface for PDL.  The\nmain distribution site is CPAN; the development repository is on\ngithub.com.\n\n=cut\n\n=head1 NAME\n\nPDL::Graphics::Simple - Simple backend-independent plotting for PDL\n\n=head1 SYNOPSIS\n\n # Simple interface - throw plots up on-screen, ASAP\n use PDL::Graphics::Simple;\n imag $a;                     # Display an image PDL\n imag $a, 0, 300;             # Display with color range\n line $rrr, $fit;             # Plot a line\n\n points $rr, $sec;            # Plot points\n hold;                        # Hold graphics so subsequent calls overplot\n line $rrr, $fit;             # Overplot a line in a contrasting color\n release;                     # Release graphics\n\n # Object interface - simple plotting, to file or screen\n $w = pgswin( size=\u003e[8,4], multi=\u003e[2,2] ); # 2x2 plot grid on an 8\"x4\" window\n $w = pgswin( size=\u003e[1000,1000,'px'], output=\u003e'plot.png' ); # output to a PNG\n\n $w-\u003eplot( with=\u003e'points', $rr, $sec, with=\u003e'line', $rrr, $fit,\n           {title=\u003e\"Points and fit\", xlabel=\u003e\"Abscissa\", ylabel=\u003e\"Ordinate\"});\n\n=head1 DESCRIPTION\n\nPDL can plot through a plethora of external plotting modules.  Each\nmodule tends to be less widely available than Perl itself, and to\nrequire an additional step or two to install.  For simple applications\n(\"throw up an image on the screen\", or \"plot a curve\") it is useful to\nhave a subset of all plotting capability available in a backend-independent\nlayer.  PDL::Graphics::Simple provides that capability.\n\nPDL::Graphics::Simple implements all the functionality used in the\nPDL::Book examples, with identical syntax.  It also generalizes that\nsyntax - you can use ::Simple graphics, with slight syntactical\ndifferences, in the same manner that you would use any of the engine\nmodules.  See the Examples below for details.\n\nThe plot you get will always be what you asked for, regardless of\nwhich plotting engine you have installed on your system.\n\nOnly a small subset of PDL's complete graphics functionality is\nsupported -- each individual plotting module has unique advantages and\nfunctionality that are beyond what PDL::Graphics::Simple can do.  Only\n2-D plotting is supported.  For 3-D plotting, use\nL\u003cPDL::Graphics::Gnuplot\u003e or L\u003cPDL::Graphics::TriD\u003e directly.\n\nWhen plotting to a file, the file output is not guaranteed to be\npresent until the plot object is destroyed (e.g. by being undefed or\ngoing out of scope).\n\n=head1 STATE OF DEVELOPMENT\n\nPDL::Graphics::Simple currently supports most of the\nplanned functionality.  It is being released as a beta\ntest to determine if it meets users' needs and gain feedback on\nthe API -- so please give feedback!\n\n=head1 SUPPORTED GRAPHICS ENGINES\n\nPDL::Graphics::Simple includes support for the following graphics\nengines.  Additional driver modules can be loaded dynamically; see\nC\u003cregister\u003e, below.  Each of the engines has unique capabilities and\nflavor that are not captured in PDL::Graphics::Simple - you are\nencouraged to look at the individual modules for more capability!\n\n=over 3\n\n=item * Gnuplot (via PDL::Graphics::Gnuplot)\n\nGnuplot is an extremely richly featured plotting package that offers\nmarkup, rich text control, RGB color, and 2-D and 3-D plotting.  Its\noutput is publication quality.  It is supported on POSIX systems,\nMacOS, and Microsoft Windows, and is available from most package\nmanagers.\n\n=item * PGPLOT  (via PDL::Graphics::PGPLOT::Window)\n\nPGPLOT is venerable and nearly as fully featured as Gnuplot for 2-D\nplotting.  It lacks RGB color output. It does have rich text control,\nbut uses simple plotter fonts that are generated internally.  It\nis supported on MacOS and POSIX, but is not as widely available as\nGnuplot.\n\n=item * PLplot (via PDL::Graphics::PLplot)\n\nPLplot is a moderately full featured plotting package that\ngenerates publication quality output with a simple high-level interface.\nIt is supported on MacOS and POSIX.\n\n=item * Prima (via PDL::Graphics::Prima)\n\nPrima is based around a widget paradigm that enables complex\ninteraction with data in real-time, and it is highly optimized for\nthat application.  It is not as mature as the other platforms,\nparticularly for static plot generation to files.  This means that\nPDL::Graphics::Simple does not play to its considerable strengths,\nalthough Prima is serviceable and fast in this application.  Please\nrun the Prima demo in the perldl shell for a better sample of Prima's\ncapabilities.\n\n=back\n\n=head1 EXAMPLES\n\nPDL::Graphics::Simple can be called using plot-atomic or curve-atomic\nplotting styles, using a pidgin form of calls to any of the main\nmodules.  The examples are divided into Book-like (very simple),\nPGPLOT-like (curve-atomic), and Gnuplot-like (plot-atomic) cases.\n\nThere are three main styles of interaction with plot objects that\nPDL::Graphics::Simple supports, reflective of the pre-existing\nmodules' styles of interaction.  You can mix-and-match them to match\nyour particular needs and coding style.  Here are examples showing\nconvenient ways to call the code.\n\n=head2 First steps (non-object-oriented)\n\nFor the very simplest actions there are non-object-oriented shortcuts.\nHere are some examples of simple tasks, including axis labels and plot\ntitles.  These non-object-oriented shortcuts are useful for display\nwith the default window size.  They make use of a package-global plot\nobject.\n\nThe non-object interface will keep using the last plot engine you used\nsuccessfully.  On first start, you can specify an engine with the\nenvironment variable C\u003cPDL_SIMPLE_ENGINE\u003e. As of 1.011, only that will be tried, but\nif you didn't specify one, all known engines are tried in alphabetical\norder until one works.\n\nThe value of C\u003cPDL_SIMPLE_ENGINE\u003e should be the \"shortname\" of the\nengine, currently:\n\n=over\n\n=item C\u003cgnuplot\u003e\n\n=item C\u003cplplot\u003e\n\n=item C\u003cpgplot\u003e\n\n=item C\u003cprima\u003e\n\n=back\n\n=over 3\n\n=item * Load module and create line plots\n\n use PDL::Graphics::Simple;\n $x = xvals(51)/5;\n $y = $x**3;\n\n $y-\u003eline;\n line( $x, $y );\n line( $x, $y, {title=\u003e\"My plot\", ylabel=\u003e \"Ordinate\", xlabel=\u003e\"Abscissa\"} );\n\n=item * Bin plots\n\n $y-\u003ebins;\n bins($y, {title=\u003e\"Bin plot\", xl=\u003e\"Bin number\", yl=\u003e\"Count\"} );\n\n=item * Point plots\n\n $y-\u003epoints;\n points($y, {title=\u003e\"Points plot\"});\n\n=item * Logarithmic scaling\n\n line( $y, { log=\u003e'y' } );    # semilog\n line( $y, { log=\u003e'xy' } );   # log-log\n\n=item * Image display\n\n $im = 10 * sin(rvals(101,101)) / (10 + rvals(101,101));\n imag $im;          # Display image\n imag $im, 0, 1;    # Set lower/upper color range\n\n=item * Overlays\n\n points($x, $y, {logx=\u003e1});\n hold;\n line($x, sqrt($y)*10);\n release;\n\n\n=item * Justify aspect ratio\n\n imag $im, {justify=\u003e1}\n points($x, $y, {justify=\u003e1});\n\n=item * Erase/delete the plot window\n\n erase();\n\n=back\n\n=head2 Simple object-oriented plotting\n\nMore functionality is accessible through direct use of the PDL::Graphics::Simple\nobject.  You can set plot size, direct plots to files, and set up multi-panel plots.\n\nThe constructor accepts window configuration options that set the plotting\nenvironment, including size, driving plot engine, output, and multiple\npanels in a single window.\n\nFor interactive/display plots, the plot is rendered immediately, and lasts until\nthe object is destroyed.  For file plots, the file is not guaranteed to exist\nand be correct until the object is destroyed.\n\nThe basic plotting method is C\u003cplot\u003e.  C\u003cplot\u003e accepts a collection of\narguments that describe one or more \"curves\" (or datasets) to plot,\nfollowed by an optional plot option hash that affects the entire plot.\nOverplotting is implemented via plot option, via a held/released state\n(as in PGPLOT), and via a convenience method C\u003coplot\u003e that causes the\ncurrent plot to be overplotted on the previous one.\n\nPlot style (line/points/bins/etc.) is selected via the C\u003cwith\u003e curve option.\nSeveral convenience methods exist to create plots in the various styles.\n\n=over 3\n\n=item * Load module and create basic objects\n\n use PDL::Graphics::Simple;\n $x = xvals(51)/5;\n $y = $x**3;\n\n $win = pgswin();                       # plot to a default-shape window\n $win = pgswin( size=\u003e[4,3] );          # size is given in inches by default\n $win = pgswin( size=\u003e[10,5,'cm'] );    # You can feed in other units too\n $win = pgswin( out=\u003e'plot.ps' );       # Plot to a file (type is via suffix)\n $win = pgswin( engine=\u003e'gnuplot' );    # Pick a particular plotting engine\n $win = pgswin( multi=\u003e[2,2] );         # Set up for a 2x2 4-panel plot\n\n=item * Simple plots with C\u003cplot\u003e\n\n $win-\u003eplot( with=\u003e'line', $x, $y, {title=\u003e\"Simple line plot\"} );\n $win-\u003eplot( with=\u003e'errorbars', $x, $y, sqrt($y), {title=\u003e\"Error bars\"} );\n $win-\u003eplot( with=\u003e'circles', $x, $y, sin($x)**2 );\n\n=item * Plot overlays\n\n # All at once\n $win-\u003eplot( with=\u003e'line', $x, $y,   with=\u003e'circles', $x, $y/2, sqrt($y)  );\n\n # Using oplot (IDL-style; PLplot-style)\n $win-\u003eplot(  with=\u003e'line', $x, $y );\n $win-\u003eoplot( with=\u003e'circles', $x, $y/2, sqrt($y) );\n\n # Using object state (PGPLOT-style)\n $win-\u003eline(  $x, $y );\n $win-\u003ehold;\n $win-\u003ecircles( $x, $y/2, sqrt($y) );\n $win-\u003erelease;\n\n=back\n\n\n=head1 FUNCTIONS\n\n=cut\n=head2 show\n\n=for usage\n\n PDL::Graphics::Simple::show\n\n=for ref\n\nC\u003cshow\u003e lists the supported engines and a one-line synopsis of each.\n\n=cut\n=head2 pgswin - exported constructor\n\n=for usage\n\n $w = pgswin( %opts );\n\n=for ref\n\nC\u003cpgswin\u003e is a constructor that is exported by default into the using package. Calling\nC\u003cpgswin(%opts)\u003e is exactly the same as calling C\u003c\u003c PDL::Graphics::Simple-\u003enew(%opts) \u003e\u003e.\n\n\n=head2 new\n\n=for usage\n\n $w = PDL::Graphics::Simple-\u003enew( %opts );\n\n=for ref\n\nC\u003cnew\u003e is the main constructor for PDL::Graphics::Simple.  It accepts a list of options\nabout the type of window you want:\n\n=over 3\n\n=item engine\n\nIf specified, this must be one of the supported plotting engines.  You\ncan use a module name or the shortened name.  If you don't give one,\nthe constructor will try the last one you used, or else scan through\nexisting modules and pick one that seems to work.  It will first check\nthe environment variable C\u003cPDL_SIMPLE_ENGINE\u003e, and as of 1.011, only that will be tried, but\nif you didn't specify one, all known engines are tried in alphabetical\norder until one works.\n\n=item size\n\nThis is a window size as an ARRAY ref containing [width, height,\nunits].  If no units are specified, the default is \"inches\".  Accepted\nunits are \"in\",\"pt\",\"px\",\"mm\", and \"cm\". The conversion used for pixels\nis 100 px/inch.\n\n=item type\n\nThis describes the kind of plot to create, and should be either \"file\"\nor \"interactive\" - though only the leading character is checked.  If\nyou don't specify either C\u003ctype\u003e or C\u003coutput\u003e (below), the default is\n\"interactive\". If you specify only C\u003coutput\u003e, the default is \"file\".\n\n=item output\n\nThis should be a window number or name for interactive plots, or a\nfile name for file plots.  The default file name is \"plot.png\" in the\ncurrent working directory.  Individual plotting modules all support at\nleast '.png', '.pdf', and '.ps' -- via format conversion if necessary.\nMost other standard file types are supported but are not guaranteed to\nwork.\n\n=item multi\n\nThis enables plotting multiple plots on a single screen.  You feed in\na single array ref containing (nx, ny).  Subsequent calls to plot\nsend graphics to subsequent locations on the window.  The ordering\nis always horizontal first, and left-to-right, top-to-bottom.\n\n=back\n\n=cut\n=head2 plot\n\n=for usage\n\n $w = PDL::Graphics::Simple-\u003enew( %opts );\n $w-\u003eplot($data);\n\n=for ref\n\nC\u003cplot\u003e plots zero or more traces of data on a graph.  It accepts two kinds of\noptions: plot options that affect the whole plot, and curve options\nthat affect each curve.  The arguments are divided into \"curve blocks\", each\nof which contains a curve options hash followed by data.\n\nIf the last argument is a hash ref, it is always treated as plot options.\nIf the first and second arguments are both hash refs, then the first argument\nis treated as plot options and the second as curve options for the first curve\nblock.\n\n=head3 Plot options:\n\n=over 3\n\n=item oplot\n\nIf this is set, then the plot overplots a previous plot.\n\n=item title\n\nIf this is set, it is a title for the plot as a whole.\n\n=item xlabel\n\nIf this is set, it is a title for the X axis.\n\n=item ylabel\n\nIf this is set, it is a title for the Y axis.\n\n=item xrange\n\nIf this is set, it is a two-element ARRAY ref containing a range for\nthe X axis.  If it is clear, the axis is autoscaled.\n\n=item yrange\n\nIf this is set, it is a two-element ARRAY ref containing a range for\nthe Y axis.  If it is clear, the axis is autoscaled.\n\n=item logaxis\n\nThis should be empty, \"x\", \"y\", or \"xy\" (case and order insensitive).\nNamed axes are scaled logarithmically.\n\n=item crange\n\nIf this is set, it is a two-element ARRAY ref containing a range for\ncolor values, full black to full white.  If it is clear, the engine or\nplot module is responsible for setting the range.\n\n=item wedge\n\nIf this is set, then image plots get a scientific colorbar on the\nright side of the plot.  (You can also say \"colorbar\", \"colorbox\", or \"cb\" if\nyou're more familiar with Gnuplot).\n\n=item justify\n\nIf this is set to a true value, then the screen aspect ratio is adjusted\nto keep the Y axis and X axis scales equal -- so circles appear circular, and\nsquares appear square.\n\n=item legend (EXPERIMENTAL)\n\nThe \"legend\" plot option is intended for full support but it is currently\nexperimental:  it is not fully implemented in all the engines, and\nimplementation is more variable than one would like in the engines that\ndo support it.\n\nThis controls whether and where a plot legend should be placed.  If\nyou set it, you supply a combination of 't','b','c','l', and 'r':\nindicating top, bottom, center, left, right position for the plot\nlegend.  For example, 'tl' for top left, 'tc' for center top, 'c' or\n'cc' for dead center.  If left unset, no legend will be plotted.  If\nyou set it but don't specify a position (or part of one), it defaults\nto top and left.\n\nIf you supply even one 'key' curve option in the curves, legend defaults\nto the value 'tl' if it isn't specified.\n\n=back\n\n=head3 Curve options:\n\n=over 3\n\n=item with\n\nThis names the type of curve to be plotted.  See below for supported curve types.\n\n=item key\n\nThis gives a name for the following curve, to be placed in a master plot legend.\nIf you don't specify a name but do call for a legend, the curve will be named\nwith the plot type and number (e.g. \"line 3\" or \"points 4\").\n\n=item width\n\nThis lets you specify the width of the line, as a multiplier on the standard\nwidth the engine uses.  That lets you pick normal-width or extra-bold lines\nfor any given curve.  The option takes a single positive natural number.\n\n=item style\n\nYou can specify the line style in a very limited way -- as a style\nnumber supported by the backend.  The styles are generally defined by\na mix of color and dash pattern, but the particular color and dash\npattern depend on the engine in use. The first 30 styles are\nguaranteed to be distinguishable. This is useful to produce, e.g.,\nmultiple traces with the same style. C\u003c0\u003e is a valid value.\n\n=back\n\n=head3 Curve types supported\n\n=over 3\n\n=item points\n\nThis is a simple point plot.  It takes 1 or 2 columns of data.\n\n=item lines\n\nThis is a simple line plot. It takes 1 or 2 columns of data.\n\n=item bins\n\nStepwise line plot, with the steps centered on each X value.  1 or 2 columns.\n\n=item errorbars\n\nSimple points-with-errorbar plot, with centered errorbars.  It takes 2\nor 3 columns, and the last column is the absolute size of the errorbar (which\nis centered on the data point).\n\n=item limitbars\n\nSimple points-with-errorbar plot, with asymmetric errorbars.  It takes\n3 or 4 columns, and the last two columns are the absolute low and high\nvalues of the errorbar around each point (specified relative to the\norigin, not relative to the data point value).\n\n=item circles\n\nPlot unfilled circles.  Requires 2 or 3 columns of data; the last\ncolumn is the radius of each circle.  The circles are circular in\nscientific coordinates, not necessarily in screen coordinates (unless\nyou specify the \"justify\" plot option).\n\n=item image\n\nThis is a monochrome or RGB image.  It takes a 2-D or 3-D array of\nvalues, as (width x height x color-index).  Images are displayed in\na sepiatone color scale that enhances contrast and preserves intensity\nwhen converted to grayscale.  If you use the convenience routines\n(C\u003cimage\u003e or C\u003cimag\u003e), the \"justify\" plot option defaults to 1 -- so\nthe image will be displayed with square pixel aspect.  If you use\nC\u003c\u003c plot(with=\u003e'image' ...) \u003e\u003e, \"justify\" defaults to 0 and you will have\nto set it if you want square pixels.\n\nFor RGB images, the numerical values need to be in the range 0-255,\nas they are interpreted as 8 bits per plane colour values. E.g.:\n\n  $w = pgswin(); # plot to a default-shape window\n  $w-\u003eimage( pdl(xvals(9,9),yvals(9,9),rvals(9,9))*20 );\n\n  # or, from an image on disk:\n  $image_data = rpic( 'my-image.png' )-\u003emv(0,-1); # need RGB 3-dim last\n  $w-\u003eimage( $image_data );\n\nIf you have a 2-D field of values that you would like to see with a heatmap:\n\n  use PDL::Graphics::ColorSpace;\n  sub as_heatmap {\n    my ($d) = @_;\n    my $max = $d-\u003emax;\n    die \"as_heatmap: can't work if max == 0\" if $max == 0;\n    $d /= $max; # negative OK\n    my $hue   = (1 - $d)*240;\n    $d = cat($hue, pdl(1), pdl(1));\n    (hsv_to_rgb($d-\u003emv(-1,0)) * 255)-\u003ebyte-\u003emv(0,-1);\n  }\n  $w-\u003eimage( as_heatmap(rvals 300,300) );\n\n=item contours\n\nAs of 1.012. Draws contours. Takes a 2-D array of values, as (width x\nheight), and optionally a 1-D vector of contour values.\n\n=item fits\n\nAs of 1.012. Displays an image from an ndarray with a FITS header.\nUses C\u003cCUNIT[12]\u003e etc to make X \u0026 Y axes including labels.\n\n=item polylines\n\nAs of 1.012. Draws polylines, with 2 arguments (C\u003c$xy\u003e, C\u003c$pen\u003e).\nThe \"pen\" has value 0 for the last point in that polyline.\n\n  use PDL::Transform::Cartography;\n  use PDL::Graphics::Simple qw(pgswin);\n  $coast = earth_coast()-\u003eglue( 1, scalar graticule(15,1) );\n  $w = pgswin();\n  $w-\u003eplot(with =\u003e 'polylines', $coast-\u003eclean_lines);\n\n=item labels\n\nThis places text annotations on the plot.  It requires three input\narguments: the X and Y location(s) as PDLs, and the label(s) as a list\nref.  The labels are normally left-justified, but you can explicitly\nset the alignment for each one by beginning the label with \"\u003c\" for\nleft \"|\" for center, and \"\u003e\" for right justification, or a single \" \"\nto denote default justification (left).\n\n=back\n\n=cut\n=head2 oplot\n\n=for usage\n\n $w = PDL::Graphics::Simple-\u003enew( %opts );\n $w-\u003eplot($data);\n $w-\u003eoplot($more_data);\n\n=for ref\n\nC\u003coplot\u003e is a convenience interface.  It is exactly\nequivalent to C\u003cplot\u003e except it sets the plot option C\u003coplot\u003e,\nso that the plot will be overlain on the previous one.\n\n=cut\n=head2 line, points, image, imag, cont\n\n=for usage\n\n # Object-oriented convenience\n $w = PDL::Graphics::Simple-\u003enew( % opts );\n $w-\u003eline($data);\n\n # Very Lazy Convenience\n $a = xvals(50);\n lines $a;\n $im = sin(rvals(100,100)/3);\n imag $im;\n imag $im, 0, 1, {title=\u003e\"Bullseye?\", j=\u003e1};\n\n=for ref\n\nC\u003cline\u003e, C\u003cpoints\u003e, and C\u003cimage\u003e are convenience\ninterfaces.  They are exactly equivalent to C\u003cplot\u003e except that\nthey set the default \"with\" curve option to the appropriate\nplot type.\n\nC\u003cimag\u003e is even more DWIMMy for PGPLOT users or PDL Book readers:\nit accepts up to three non-hash arguments at the start of the\nargument list.  The second and third are taken to be values for\nthe C\u003ccrange\u003e plot option.\n\nC\u003ccont\u003e resembles the PGPLOT function.\n\n=cut\n=head2 erase\n\n=for usage\n\n use PDL::Graphics::Simple qw/erase hold release/;\n line xvals(10), xvals(10)**2 ;\n sleep 5;\n erase;\n\n=for ref\n\nC\u003cerase\u003e removes a global plot window.  It should not be called as a method.\nTo remove a plot window contained in a variable, undefine it.\n\n=cut\n=head2 hold\n\n=for usage\n\n use PDL::Graphics::Simple;\n line xvals(10);\n hold;\n line xvals(10)**0.5;\n\n=for ref\n\nCauses subsequent plots to be overplotted on any existing one.  Called\nas a function with no arguments, C\u003chold\u003e applies to the global object.\nCalled as an object method, it applies to the object.\n\n=cut\n=head2 release\n\n=for usage\n\n use PDL::Graphics::Simple;\n line xvals(10);\n hold;\n line xvals(10)**0.5;\n release;\n line xvals(10)**0.5;\n\n=for ref\n\nReleases a hold placed by C\u003chold\u003e.\n\n=cut\n=head2 register\n\n=for usage\n\n PDL::Graphics::Simple::register( \\%description );\n\n=for ref\n\nThis is the registration mechanism for new driver methods for\nC\u003cPDL::Graphics::Simple\u003e.  Compliant drivers should announce\nthemselves at compile time by calling C\u003cregister\u003e, passing\na hash ref containing the following keys:\n\n=over\n\n=item shortname\n\nThis is the short name of the engine, by which users refer to it colloquially.\n\n=item module\n\nThis is the fully qualified package name of the module itself.\n\n=item engine\n\nThis is the fully qualified package name of the Perl API for the graphics engine.\n\n=item synopsis\n\nThis is a brief string describing the backend\n\n=item pgs_api_version\n\nThis is a one-period version number of PDL::Graphics::Simple against which\nthe module has been tested.  A warning will be thrown if the version isn't the\nsame as C\u003c$PDL::Graphics::Simple::API_VERSION\u003e.\n\nThat value will only change when the API changes, allowing the modules\nto be released independently, rather than with every version of\nPDL::Graphics::Simple as up to 1.010.\n\n=back\n\n=cut\n=head1 IMPLEMENTATION\n\nPDL::Graphics::Simple defines an object that represents a plotting\nwindow/interface.  When you construct the object, you can either\nspecify a backend or allow PDL::Graphics::Simple to find a backend\nthat seems to work on your system.  Subsequent plotting commands are\ntranslated and passed through to that working plotting module.\n\nPDL::Graphics::Simple calls are dispatched in a two-step process. The\nmain module curries the arguments, parsing them into a regularized\nform and carrying out DWIM optimizations. The regularized arguments\nare passed to implementation classes that translate them into the APIs of their\nrespective plot engines.  The classes are very simple and implement\nonly a few methods, outlined below.  They are intended only to be\ncalled by the PDL::Graphics::Simple driver, which limits the need for\nargument processing, currying, and parsing. The classes are thus\nresponsible only for converting the regularized parameters to plot\ncalls in the form expected by their corresponding plot modules.\n\nPDL::Graphics::Simple works through a call-and-dispatch system rather\nthan taking full advantage of inheritance.  That is for two reasons:\n(1) it makes central control mildly easier going forward, since calls\nare dispatched through the main module; and (2) it makes the\nnon-object-oriented interface easier to implement since the main\ninterface modules are in one place and can access the global object\neasily.\n\n=head2 Interface class methods\n\nEach interface module supports the following methods:\n\n=cut\n=head3 check\n\nC\u003ccheck\u003e attempts to load the relevant engine module and test that it\nis working.  In addition to returning a boolean value indicating\nsuccess if true, it registers its success or failure in\nthe main $mods hash, under the \"ok\" flag.  If there is a failure that\ngenerates an error message, the error is logged under the \"msg\" flag.\n\nC\u003ccheck\u003e accepts one parameter, \"force\".  If it is missing or false,\nand \"ok\" is defined, check just echoes the prior result.  If it is\ntrue, then check actually checks the status regardless of the \"ok\"\nflag.\n\n=head3 new\n\nC\u003cnew\u003e creates and returns an appropriate plot object, or dies on\nfailure.\n\nEach C\u003cnew\u003e method should accept the following options, defined as in\nthe description for PDL::Graphics::Simple::new (above).  There is\nno need to set default values as all arguments should be set to\nreasonable values by the superclass.\n\nFor file output, the method should autodetect file type by dot-suffix.\nAt least \".png\" and \".ps\" should be supported.\n\nRequired options: C\u003csize\u003e, C\u003ctype\u003e, C\u003coutput\u003e, C\u003cmulti\u003e.\n\n=head3 plot\n\nC\u003cplot\u003e generates a plot.  It should accept a standardized collection\nof options as generated by the PDL::Graphics::Simple plot method:\nstandard plot options as a hash ref, followed by a list of curve\nblocks.  It should render either a full-sized plot that fills the plot\nwindow or, if the object C\u003cmulti\u003e option was set on construction, the\ncurrent subwindow.  For interactive plot types it should act as an\natomic plot operation, displaying the complete plot.  For file plot\ntypes the atomicity is not well defined, since multiplot grids may\nbe problematic, but the plot should be closed as soon as practical.\n\nThe plot options hash contains the plot options listed under C\u003cplot\u003e,\nabove, plus one additional flag - C\u003coplot\u003e - that indicates the new\ndata is to be overplotted on top of whatever is already present in the\nplotting window.  All options are present in the hash. The C\u003ctitle\u003e,\nC\u003cxlabel\u003e, C\u003cylabel\u003e, and C\u003clegend\u003e options default to undef, which\nindicates the corresponding plot feature should not be rendered.  The\nC\u003coplot\u003e, C\u003cxrange\u003e, C\u003cyrange\u003e, C\u003ccrange\u003e, C\u003cwedge\u003e, and C\u003cjustify\u003e\nparameters are always both present and defined.\n\nIf the C\u003coplot\u003e plot option is set, then the plot should be overlain on\na previous plot - otherwise the module should display a fresh plot.\n\nEach curve block consists of an ARRAY ref with a hash in the 0 element\nand all required data in the following elements, one PDL per\n(ordinate/abscissa).  For 1-D plot types (like points and lines) the\nPDLs must be 1D.  For image plot types the lone PDL must be 2D\n(monochrome) or 3D(RGB).\n\nThe hash in the curve block contains the curve options for that\nparticular curve.  They are all set to have reasonable default values.\nThe values passed in are C\u003cwith\u003e and C\u003ckey\u003e.  If the C\u003clegend\u003e\noption is undefined, then the curve should not be placed into a plot\nlegend (if present).\n\n=head1 ENVIRONMENT\n\nSetting some environment variables affects operation of the module:\n\n=head2 PDL_SIMPLE_ENGINE\n\nSee L\u003c/new\u003e.\n\n=head2 PDL_SIMPLE_DEVICE\n\nIf this is a meaningful thing for the given engine, this value will be\nused instead of the driver module guessing.\n\n=head2 PDL_SIMPLE_OUTPUT\n\nOverrides passed-in arguments, to create the given file as output.\nIf it contains C\u003c%d\u003e, then with Gnuplot that will be replaced with an\nincreasing number (an amazing L\u003cPDL::Graphics::Gnuplot\u003e feature).\n\n=head1 TO-DO\n\nDeal with legend generation.  In particular: adding legends with multi-call\nprotocols is awkward and leads to many edge cases in the internal protocol.\nThis needs more thought.\n\n=head1 REPOSITORY\n\nL\u003chttps://github.com/PDLPorters/PDL-Graphics-Simple\u003e\n\n=head1 AUTHOR\n\nCraig DeForest, C\u003c\u003c \u003ccraig@deforest.org\u003e \u003e\u003e\n\n\n=head1 LICENSE AND COPYRIGHT\n\nCopyright 2013 Craig DeForest\n\nThis program is free software; you can redistribute it and/or modify\nit under the terms of either: the Gnu General Public License v1 as\npublished by the Free Software Foundation; or the Perl Artistic\nLicense included with the Perl language.\n\nsee http://dev.perl.org/licenses/ for more information.\n\n=cut\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdlporters%2Fpdl-graphics-simple","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpdlporters%2Fpdl-graphics-simple","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdlporters%2Fpdl-graphics-simple/lists"}