Importing/Exporting Particle Data

This feature enables you to export particle data to a simple text file which can then be imported into other applications. You can also re-import this data, or import data from files saved by other applications.

Very importantly, this is not a cache system. It is a snapshot of particle data intended to allow data interchange with other applications. To do this, there are two objects in X-Particles, and you should refer to these for details of how to use them. They are:

Overview

It is sometimes desirable to create particles from data imported from another application. X-Particles already contains support for cache files from various source such as RealFlow (see the Cache object for details) but data may be available from a wide variety of other sources. Star maps, for example, are ideally suited as a source for particle creation.

To use such data, you can use the Data Importer object. Put simply, this reads data from a source file and uses that data to create new particles. Of course, you might also want to do the reverse: export particle data from X-Particles in a format other applications can read for their own purpose. This is what the Data Exporter object does.

Data format

To exchange data with other applications, the data needs to be in a common format understood by many different applications. X-Particles imports and exports data in comma-separated value (CSV) format. This is a simple text file in which individual items of data are separated by a comma or other delimiting character. As such, it can be saved or loaded ( and edited) by anything from simple text editors to spreadsheets, databases, and a wide range of other applications such as After Effects.

The CSV file format is a simple one and X-Particles follows the standard definition of these files. If you are interested, the formal definition can be found at https://tools.ietf.org/html/rfc4180. Although termed 'comma-separated' as the comma is the most common field delimiter, these files may use tabs, semicolons, or any delimiter character. You can choose the delimiter when loading or saving the data.

Note: the filename extension does NOT have to be .csv. X-Particles doesn't care about the extension.

Data header

One of the most important points about a CSV file is that it may (but does not have to) contain a header row. This must be the first line in the file and simply assigns a name to each data field. So if you had a file which contained three items of data, such as the X, Y, and Z values defining a point in 3D space, you might have a header row containing the names like this:

PositionX,PositionY,PositionZ

followed by one or more rows of data with the actual values, like this:

-0.066,-47.528,76.507

        -18.731,-18.265,76.511

        -44.914,27.465,75.245

      -47.211,1.439,76.979

      ...and so on...

The header is not required and the data importer will handle files with and without it; the exporter lets you choose whether to export the data field names or not.

A CSV file does not have to have a header row, but the vast majority do. You will use the names given in the header row to map items of particle data to the fields in the data file. If there is no header row, you still need the names to map, so if you import such a file the data importer will generate a standard set of headers, which will be Field1, Field2, Field3...Fieldn, where 'n' is the number of data fields. You then use these names to map fields to particle data.

Fortunately most CSV files have such a row. Even if a file does not, you can easily add a header row with a text editor, and it must be the first line in the file. Just remember to add the correct number of field names (1 name per data field) and separate them with a delimiter character. This MUST be the same delimiter as is used in the rest of the file.

Inspecting and editing .CSV files

At some point you will probably want to look at the file you are intending to import to obtain the data header names and maybe edit it as well, before importing it. To do this you need a text editor; although you can use simple editors such as Notepad, it is recommended you obtain a better editor such as Notepad++ (Windows) or the excellent TextWrangler (OSX). Both are free. You can even load the file into a spreadsheet such as Microsoft Excel or OpenOffice Calc, which can be useful if you want to manipulate some of the data before importing it.

Some worked examples

At this point that's all you need to know and it's probably more helpful to look at three worked examples so you can see how to use this facility. The examples are:

Exporting data from Cinema 4D into X-Particles

Importing data into Cinema 4D from X-Particles