XYZ format provides raster data in ASCII text files.  Manifold can import as well as export data using XYZ format.  


Each row in an XYZ file provides data for a single pixel using three text numbers that are separated by white space characters and an optional delimiter character.  Unlike typical XYZ importers that allow only commas or semicolons as delimiter characters, Manifold's XYZ dataport allows delimiter characters to be any text character that is not used in text representations of numbers, that is, any text character outside the set 0123456789.+-eE.    That allows use of common delimiters like pipe characters, slash characters, and so on that are used in CSV or quasi-CSV files that convey raster data as triplets of numbers, one triplet in each row.    Such CSV files can therefore be imported as XYZ files by simply renaming them to use an .xyz file extension.


Manifold's XYZ dataport always reads text numbers as X, Y, and Z order.  Any initial text lines giving field names are ignored.   


Manifold's XYZ dataport can read XYZ files that provide coordinates in any order, and the spacing between each coordinate row need not be constant.  That is much more versatile than XYZ readers based on GDAL which require rows with the same Y coordinates to be placed on consecutive lines, with rows further organized by increasing X values.   The GDAL XYZ reader is basically limited to regular grids that provide coordinates in a specific order.  The Manifold XYZ dataport can read coordinates in any order, and it can read coordinates that do not form a regular grid.

Coordinate Systems

XYZ format does not provide any coordinate system information.   If the XYZ file is accompanied by a like-named auxiliary file that provides projection information in any of the formats Manifold reads, that is, .prj, PAM XML, world files as .xzw or .xyz, Release 8 .xml, or Release 9 .mapmeta files, Manifold will read the auxiliary file and apply the projection information it contains.  See the discussion in the Projections topic.


If the XYZ fle is not accompanied with one of the standard auxiliary files used for conveying coordinate system information, we should be on the lookout for any metadata that accompanied the XYZ file we are using, to be able to assign the coordinate system to use via the Assign Coordinate System dialog.   


When exporting to XYZ, a .mapmeta file will be written.  Only single-channel images can be exported to XYZ.

Importing XYZ Files

XYZ files can be linked, but since ASCII text files are a very low performance format, it makes more sense to import data from XYZ files.



To import from XYZ format:


  1. Choose File-Import from the main menu.

  2. In the Import dialog browse to the folder containing data of interest.

  3. Double-click the file ending in .xyz for the data of interest.

  4. A table and an image will be created.




We can double-click on images that are created to view them.   



The image appears using default style.  However, it has not yet had a coordinate system assigned.    


After some searching, we discover a metadata file on the website from which we downloaded the XYZ file that gives metadata in XML format.  We open the metadata file in Notepad, and in the metadata we find a claim that the coordinate system in use is Universal Transverse Mercator zone 15.  Since this is a data set in Arkansas, USA, we assume that is Universal Transverse Mercator zone 15 (N), for north.    We use the Assign Initial Coordinate System dialog to assign that coordinate system to the image.    If the image had some wrong coordinate system assigned, we could use the  Repair Initial Coordinate System dialog to assign Universal Transverse Mercator zone 15 (N) as the coordinate system it should use.



Once the correct, Universal Transverse Mercator zone 15 (N), coordinate system has been assigned, we can create a new map using Bing streets as a background layer and our imported image as a layer.  The image appears where it should be, in Arkansas.  Note how the image uses transparent pixels where there were no pixel values provided in the XYZ file.


For a more interesting image, we use the Style pane to color the image using a palette and to apply hill shading, as seen below in a zoomed-in view.  Greater depths are shown as blue colors.



That provides a more informative display.  In the illustration above, we have added a Bing satellite image server layer above the streets layer, to see what the terrain around the lake looks like.  The display shows bathymetry (depths) in Beaver Lake, Arkansas.



Whitespace - Reading XYZ with a non-space delimiter allows whitespace both before and after the delimiter character.


Big integers - Reading XYZ with integer values that do not fit into INT32 converts all values to FLOAT64.


Just say No to NaN - Reading XYZ skips NaN values. Records with such values have no business being in the file, but they might technically be there and some software packages produce files with NaN values in XYZ files.


Big XYZ is Fun XYZ - Reading XYZ supports files bigger than 4 GB.


Tiny Drift Ignored - Reading XYZ protects against tiny drift in XY values to handle regular grids more reliably.


Full Precision on Export - When exporting XYZ, the system writes all values with full precision.



See Also









GRD, Northwood .GRC, .GRD


GRD, Surfer .GRD