Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
C++ (with python bindings) library for easily reading/writing/manipulating common animation particle formats such as PDB, BGEO, PTC. See the discussion group @ http://groups.google.com/group/partio-discuss
C C++ Python
branch: master

This branch is 3 commits ahead, 74 commits behind wdas:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
src
.gitignore
CMakeLists.txt
README
SConstruct

README

===================================================================
Partio - A library for particle IO and manipulation
===================================================================

This is the initial source code release of partio a tool we used for particle
reading/writing.  It started out as an abstraction for the commonalities in
particle models (i.e. accessing many attributes associated with an index or
entity).

Geting Started
==============

I use scons for building. I'm open to adding build files for other
build systems, too. Just type scons and you will get a build
to a platform specific build directory. 

Source code overview
====================

src/
   lib/      Library code (public API in root)
   lib/core  Core library (KDtree traversal, data representations)
   lib/io    Input/Output (Different file formats)
   py/       SWIG based python bindings
   doc/      Doxygen documentation and (the start of) a manual
   tests/    Start of regression tests (I need more)
   tools/    Useful tools 
             partconv <input format> <output format>
             partinfo <particle file>
             partview <particle file>

Class Model
-----------

The goal of the library is to abstract the particle itnerface from the data
representation. That is why Partio represents particles using three classes that
inherit and provide more functionality

ParticlesInfo - Information about # of particles and attributes
ParticlesData - Read only access to all particle data
ParticlesDataMutable - Read/write access to all particle data

The functions used to get particle access are these:

readHeaders() 
   returns ParticlsInfo
   reads only the minimum data necessary to get number of particles and
   attributes

readCached()
   returns ParticlesData
   For multiple users in different threads using the same particle file
   ParticlesData

create() and read()
   returns ParticlesDataMutable   
   allows read/write access

Behind the scenes you could implement these classes however you like.  Headers
only representation is called core/ParticleHeader.{h,cpp}.  Simple
non-interleaved attributes is core/ParticleSimple.{h,cpp}.

Attribute Data Model
--------------------

All particles have the same data attributes.  They have the model that they are
of three basic types with a count of how many scalar values they have.

VECTOR[3]    
FLOAT[d]
INT[d]

VECTOR[3] and FLOAT[3] have the same data repesentations.
VECTOR[4] is invalid howver FLOAT[4] is valid as is FLOAT[1...infinity]

This seems to encompass the most common file formats for particles


Iterating
---------

There are multiple ways to access data in the API. Here are
some tips

- Use SIMD functions when possible prefer dataAsFloat(),data(arrayOfIndices) as
  opposed to data(int singleIndex) which accesses multiple pieces of data at
  once

- Cache ParticleAttributes for quick access instead of calling attributeInfo()
  over a loop of particles

- Use iterators to do linear operations over all particles They are much more
  optimized than both data() and the dataAsFloat or


Backends
--------

Behind the scenes there are SimpleParticles, ParticleHeaders, and
SimpleParticlesInterleaved.  In the future I would like to write a disk-based
cached back end that can dynamically only load the data that is necessary.
create(), read() and readCached could be augmented to create different
structures in these cases.

Readers/Writers
---------------

New readers and writers can be added in the io/ directory. You simply need to
implement the interface ParticlesInfo, ParticlesData and ParticlesDataMutable
(or as many as you need). Editing the io/readers.h to add protoypes and
io/ParticleIO.cpp to add file extension bindings should be easy.


- Andrew Selle, Walt Disney Animation Studios
Something went wrong with that request. Please try again.