XB PointStream/custom parsers

Parser Interface

There will be cases in which users have their own file format which they want to render with XB PointStream (for example, .ARA or .XML). We need to give users the ability to write their own parser and hook it into the library.

Users would write their JavaScript code which would implement the methods below. Once they do that, they would register their parser with the library by passing in an extension and their parser.

The library would then take care of the rest by creating an instance of their parser, call its methods and return a point cloud object.

/*
  The constructor of the parser.

  @param {Object} obj - collection of named functions

  These functions pass the parser back to the library since the library could
  be working with many parsers simultaneously.

  start - must occur exactly once. Has one argument, the parser itself
  end   - must occur exactly once. Has one argument, the parser itself
  parse - may occur one or many times. Has two arguments, the parser itself and a
  named collection of value types.

  See below for an example

*/
Constructor(obj)

/*
  Begins to load the resource.

  @param {String} path - path to resource
*/
load(path)


////// Getters

/*
  Get the version of this parser.
 
  @returns {String} parser version
*/
version

/*
  Get the number of points which have been parsed.

  @returns {Number} the number of points parsed so far by the parser.
*/
numParsedPoints

/*
  Get the total number of points in the point cloud, including points
  which have not yet been parsed.

  @returns {Number} the total number of points in the resource or -1 if unknown.
*/
numTotalPoints

/*
  Get the progress of the parser, how much it has parsed so far.

  @returns {Number} value between 0 to 1 or -1 if unknown.
*/
progress

/*
  The size of the resource in bytes.

  @returns {Number} the number of bytes in the resource or -1 if unknown.
*/
fileSize

/*
  The following example demonstrates how XB PointStream might use
  a particular parser.
*/

var parser;

function startCallback(parser){
  // started
}

function parseCallback(parser, attributes){
  parser.version;
  parser.numParsedPoints;
  parser.numTotalPoints;
  parser.progress;
  parser.fileSize;
}

function finishCallback(parser){
  // finished
}

// create a hypothetical parser and set the callbacks
parser = new XYZParser({ start: startCallback,
                         parse: parseCallback,
                         end: finishCallback});
// load some resource
parser.load("pointcloud.xyz");