.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "IO 3pm" .TH IO 3pm "2023-06-17" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" PDL::IO \- An overview of the modules in the PDL::IO namespace. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # At your system shell, type: \& perldoc PDL::IO \& \& # from perldl: \& pdl> ?? PDL::IO .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1PDL\s0 contains many modules for displaying, loading, and saving data. .IP "\(bu" 4 Perlish or Text-Based .Sp A few \s-1IO\s0 modules provide Perl-inspired capabilities. These are PDL::IO::Dumper and PDL::IO::Storable. PDL::IO::Misc provides simpler routines for dealing with delimited files, though its capabilities are limited to tabular or at most 3\-d data sets. .IP "\(bu" 4 Raw Format .Sp \&\s-1PDL\s0 has two modules that store their data in a raw binary format; they are PDL::IO::FastRaw and PDL::IO::FlexRaw. They are fast but the files they produce will not be readable across different architectures. These two modules are so similar that they could probably be combined. .Sp You can also directly access the data from Perl using \&\*(L"get_dataref\*(R" in PDL::Core. .IP "\(bu" 4 Data Browsing .Sp At the moment, only PDL::IO::Browser provides data browsing functionality. .IP "\(bu" 4 Image Handling .Sp \&\s-1PDL\s0 has a handful of modules that will load images into ndarrays for you. They include PDL::IO::Dicom, \s-1PDL::IO::FITS, PDL::IO::GD,\s0 PDL::IO::Pic, and PDL::IO::Pnm. However, \s-1PDL::IO::FITS\s0 should also be considered something of a general data format. .IP "\(bu" 4 Disk Caching .Sp Both PDL::IO::FastRaw and PDL::IO::FlexRaw provide for direct ndarray-to-disk mapping, but they use \s-1PDL\s0's underlying mmap functionality to do it, and that doesn't work for Windows. However, users of all operating systems can still use PDL::DiskCache, which can use any desired \s-1IO\s0 read/write functionality (though you may have to write a small wrapper function). .IP "\(bu" 4 General Data Storage Formats .Sp \&\s-1PDL\s0 has a number of modules that interface general data storage libraries. They include \s-1PDL::IO::HDF\s0 and \s-1PDL::IO::NDF\s0 (the latter is now a separate \&\s-1CPAN\s0 module). There is \s-1PDL::IO::IDL\s0. \&\s-1PDL::IO::FITS\s0 is something of a general data format, since ndarray data can be stored to a \&\s-1FITS\s0 file without loss. PDL::IO::FlexRaw and PDL::IO::FastRaw read and write data identical C's low-level \f(CW\*(C`write\*(C'\fR function and PDL::IO::FlexRaw can work with \s-1FORTRAN 77 UNFORMATTED\s0 files. FlexRaw and Storable provide general data storage capabilities. Finally, \s-1PDL\s0 can read Grib (weather-data) files using the \s-1CPAN\s0 module PDL::IO::Grib. .IP "\(bu" 4 Making Movies .Sp You can make an \s-1MPEG\s0 animation using PDL::IO::Pic's wmpeg function. .PP Here's a brief summary of all of the modules, in alphabetical order. .SS "PDL::DiskCache" .IX Subsection "PDL::DiskCache" The DiskCache module allows you to tie a Perl array to a collection of files on your disk, which will be loaded into and out of memory as ndarrays. Although the module defaults to working with \s-1FITS\s0 files, it allows you to specify your own reading and writing functions. This allows you to vastly streamline your code by hiding the unnecessary details of loading and saving files. .PP If you find yourself writing scripts to procss many data files, especially if that data processing is not necessarily in sequential order, you should consider using PDL::DiskCache. To read more, check the PDL::DiskCache documentation. .SS "PDL::IO::Browser" .IX Subsection "PDL::IO::Browser" The Browser module provides a text-based data browser for 2D data sets. .PP It uses the \s-1CURSES\s0 library to do the scrolling, so if your operating system does not have the curses library, you won't be able to install this on your machine. (Note that the package containing the header files for the \s-1CURSES\s0 library may be called \f(CW\*(C`libcurses\*(C'\fR or possibly \&\f(CW\*(C`libncurses\*(C'\fR.) .PP To see if the module is installed on your machine (and to get more information about PDL::IO::Browser), follow this link or type at the system prompt: .PP .Vb 1 \& perldoc PDL::IO::Browser .Ve .PP If you want to get more information about PDL::IO::Browser and it's not installed on your system, I'm afraid you'll have to pick out the pod from the source file, which can be found online at . .SS "PDL::IO::Dicom" .IX Subsection "PDL::IO::Dicom" \&\s-1DICOM\s0 is an image format, and this module allows you to read image files with the \s-1DICOM\s0 file format. To read more, check the PDL::IO::Dicom documentation. .SS "PDL::IO::Dumper" .IX Subsection "PDL::IO::Dumper" Provides functionality similar to Data::Dumper for ndarrays. Data::Dumper stringifies a data structure, creating a string that can be \f(CW\*(C`eval\*(C'\fRed to reproduce the original data structure. It's also usually suitable for printing, to visualize the structure. .PP To read more, check the PDL::IO::Dumper documentation. See also PDL::IO::Storable for a more comprehensive structured data solution. .SS "PDL::IO::FastRaw" .IX Subsection "PDL::IO::FastRaw" Very simple module for quickly writing, reading, and memory-mapping ndarrays to/from disk. It is fast to learn and fast to use, though you may be frustrated by its lack of options. To quote from the original \s-1POD:\s0 .PP \&\*(L"The binary files are in general \s-1NOT\s0 interchangeable between different architectures since the binary file is simply dumped from the memory region of the ndarray. This is what makes the approach efficient.\*(R" .PP This creates two files for every ndarray saved \- one that stores the raw data and another that stores the header file, which indicates the dimensions of the data stored in the raw file. Even if you save 1000 different ndarrays with the exact same dimensions, you will still need to write out a header file for each one. You cannot store multiple ndarrays in one file. .PP Note that at the time of writing, memory-mapping is not possible on Windows. .PP For more details, see PDL::IO::FastRaw. For a more flexible raw \s-1IO\s0 module, see PDL::IO::FlexRaw. .SS "\s-1PDL::IO::FITS\s0" .IX Subsection "PDL::IO::FITS" Allows basic reading and writing of \s-1FITS\s0 files. You can read more about \s-1FITS\s0 formatted files at and . It is an image format commonly used in Astronomy. .PP This module may or may not be installed on your machine. To get more information, check online at . To see if the module is installed, look for \s-1PDL::IO::FITS\s0 on your machine by typing at the system prompt: .PP .Vb 1 \& perldoc PDL::IO::FITS .Ve .SS "PDL::IO::FlexRaw" .IX Subsection "PDL::IO::FlexRaw" Somewhat smarter module (compared to FastRaw) for reading, writing, and memory mapping ndarrays to disk. In addition to everything that FastRaw can do, FlexRaw can also store multiple ndarrays in a single file, take user-specified headers (so you can use one header file for multiple files that have identical structure), and read compressed data. However, FlexRaw cannot memory-map compressed data, and just as with FastRaw, the format will not work across multiple architectures. .PP FlexRaw and FastRaw produce identical raw files and have essentially identical performance. Use whichever module seems to be more comfortable. I would generally recommend using FlexRaw over FastRaw, but the differences are minor for most uses. .PP Note that at the time of writing, memory-mapping is not possible on Windows. .PP For more details on FlexRaw, see PDL::IO::FlexRaw. .SS "\s-1PDL::IO::GD\s0" .IX Subsection "PDL::IO::GD" \&\s-1GD\s0 is a library for reading, creating, and writing bitmapped images, written in C. You can read more about the C\-library here: . .PP In addition to reading and writing .png and .jpeg files, \s-1GD\s0 allows you to modify the bitmap by drawing rectangles, adding text, and probably much more. The documentation can be found here. As such, it should probably be not only considered an \s-1IO\s0 module, but a Graphics module as well. .PP This module provides \s-1PDL\s0 bindings for the \s-1GD\s0 library, which ought not be confused with the Perl bindings. The perl bindings were developed independently and can be found at \s-1GD\s0, if you have Perl's \s-1GD\s0 bindings installed. .SS "PDL::IO::Grib" .IX Subsection "PDL::IO::Grib" A \s-1CPAN\s0 module last updated in 2000 that allows you to read Grib files. \&\s-1GRIB\s0 is a data format commonly used in meteorology. In the off-chance that you have it installed, you should read PDL::IO::Grib's documentation. .SS "\s-1PDL::IO::HDF, PDL::IO::HDF5\s0" .IX Subsection "PDL::IO::HDF, PDL::IO::HDF5" Provides an interface to \s-1HDF4\s0 and \s-1HDF5\s0 file formats, which are kinda like cross-platform binary \s-1XML\s0 files. \s-1HDF\s0 stands for \fBH\fRierarchical \fBD\fRata \&\fBF\fRormat. \s-1HDF\s0 was originally developed at the \s-1NCSA.\s0 To read more about \&\s-1HDF,\s0 see . Note that \s-1HDF5\s0 is not presently distributed with \s-1PDL,\s0 and neither \s-1HDF4\s0 nor \s-1HDF5\s0 will be installed unless you have the associated C libraries that these modules interface. Also note that the \s-1HDF5\s0 library on \s-1CPAN\s0 is rather old and somebody from \s-1HDF\s0 contacted the mailing list in the Fall of 2009 to develop new and better \&\s-1HDF5\s0 bindings for Perl. .PP You should look into the \s-1PDL::IO::HDF\s0 (4) documentation or \&\s-1PDL::IO::HDF5\s0 documentation, depending upon which module you have installed. .SS "\s-1PDL::IO::IDL\s0" .IX Subsection "PDL::IO::IDL" \&\s-1PDL\s0 has a module for reading \s-1IDL\s0 data files: \s-1PDL::IO::IDL\s0. .SS "PDL::IO::Misc" .IX Subsection "PDL::IO::Misc" Provides mostly text-based \s-1IO\s0 routines. Data input and output is restricted mostly to tabular (i.e. two-dimensional) data sets, though limited support is provided for 3d data sets. .PP Alternative text-based modules support higher dimensions, such as PDL::IO::Dumper and PDL::IO::Storable. Check the PDL::IO::Misc documentation for more details. .SS "\s-1PDL::IO::NDF\s0" .IX Subsection "PDL::IO::NDF" Starlink developed a file format for N\-Dimensional data Files, which it cleverly dubbed \s-1NDF.\s0 If you work with these files, you're in luck! Check the \s-1PDL::IO::NDF\s0 documentation for more details. .SS "PDL::IO::Pic" .IX Subsection "PDL::IO::Pic" Provides reading/writing of images to/from ndarrays, as well as creating \&\s-1MPEG\s0 animations! The module uses the netpbm library, so you will need that on your machine in order for this to work. To read more, see the PDL::IO::Pic documentation. Also look into the next module, as well as \s-1PDL::IO::GD.\s0 .SS "PDL::IO::Pnm" .IX Subsection "PDL::IO::Pnm" Provides methods for reading and writing pnm files (of which pbm is but one). Check the PDL::IO::Pnm documentation for more details. Also check out the previous module and \s-1PDL::IO::GD.\s0 .SS "\s-1PDL::IO::STL\s0" .IX Subsection "PDL::IO::STL" Read and write \s-1STL\s0 (STereo Lithography) files, containing 3D objects. There are many files available from the \*(L"Thingiverse\*(R". You can then view the data in PDL::Graphics::TriD. .SS "PDL::IO::Storable" .IX Subsection "PDL::IO::Storable" Implements the relevant methods to be able to store and retrieve ndarrays via Storable. True, you can use many methods to save a single ndarray. In contrast, this module is particularly useful if you need to save a complex Perl structure that contain ndarrays, such as an array of hashes, each of which contains ndarrays. .PP Check the PDL::IO::Storable documentation for more details. See also PDL::IO::Dumper for an alternative stringifier. .SH "Out-of-tree Third-party Modules" .IX Header "Out-of-tree Third-party Modules" .SS "\s-1PDL::IO::CSV\s0" .IX Subsection "PDL::IO::CSV" Load/save \s-1PDL\s0 from/to \s-1CSV\s0 file (optimized for speed and large data). .PP See the \s-1PDL::IO::CSV\s0 documentation. .SS "\s-1PDL::IO::DBI\s0" .IX Subsection "PDL::IO::DBI" Load \s-1PDL\s0 from a \s-1DBI\s0 handle. See \s-1PDL::IO::CSV\s0. .SS "PDL::IO::Dcm" .IX Subsection "PDL::IO::Dcm" Load \s-1PDL\s0 from a Dicom file. See PDL::IO::Dcm. .SS "PDL::IO::Touchstone" .IX Subsection "PDL::IO::Touchstone" A simple interface for reading and writing \s-1RF\s0 Touchstone files (also known as \&\*(L".sNp\*(R" files). Touchstone files contain complex-valued \s-1RF\s0 sample data for a device or \s-1RF\s0 component with some number of ports. The data is (typically) measured by a vector network analyzer under stringent test conditions. .PP The resulting files are usually provided by manufacturers so \s-1RF\s0 design engineers can estimate signal behavior at various frequencies in their circuit designs. Examples of \s-1RF\s0 components include capacitors, inductors, resistors, filters, power splitters, etc. .PP See the PDL::IO::Touchstone documentation. .SS "\s-1PDL::IO::MDIF\s0" .IX Subsection "PDL::IO::MDIF" A simple interface for reading and writing \s-1RF MDIF\s0 files (also known as \s-1MDF\s0 or \&.mdf files). \s-1MDIF\s0 files contain multiple Touchstone files in a text format for use in optimizing circuits. For example, a single \s-1MDIF\s0 file could contain the Touchstone \s-1RF\s0 data for each available value in a line of capacitors (ie, from 10pF to 1000pF) provided by a particular manufacturer. .PP See the \s-1PDL::IO::MDIF\s0 documentation .SS "PDL::IO::Image" .IX Subsection "PDL::IO::Image" Load/save \s-1PDL\s0 from/to image files. See PDL::IO::Image. .SS "\s-1PDL::IO::XLSX\s0" .IX Subsection "PDL::IO::XLSX" Load/save \s-1PDL\s0 from/to an Excel spreadsheet. See \s-1PDL::IO::XLSX\s0. .SS "PDL::NetCDF" .IX Subsection "PDL::NetCDF" Load/save \s-1PDL\s0 from/to NetCDF files. See PDL::NetCDF. .SS "PDL::IO::Nifti" .IX Subsection "PDL::IO::Nifti" Load/save \s-1PDL\s0 from/to Nifti\-1 files. See PDL::IO::Nifti. .SS "PDL::IO::Matlab" .IX Subsection "PDL::IO::Matlab" Load/save \s-1PDL\s0 from/to \s-1MATLAB\s0 files. See PDL::IO::Matlab. .SS "PDL::IO::Sereal" .IX Subsection "PDL::IO::Sereal" Load/save \s-1PDL\s0 from/to Sereal files. See PDL::IO::Sereal. .SS "\s-1PDL::CCS\s0" .IX Subsection "PDL::CCS" Has \s-1IO\s0 modules to load/save \s-1PDL\s0 from/to sparse data file formats, including \&\s-1FITS,\s0 LDA-C, MatrixMarket, PETSc. See \s-1PDL::CCS\s0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2010 David Mertens (dcmertens.perl@gmail.com). You can distribute and/or modify this document under the same terms as the current Perl license. .PP See: