npm package: @gov.nasa.jpl.honeycomb/arksml-loader
Description: Class for loading and parsing the ARKSML file format.
Latest version: 0.0.6

# ARKSML Loader

Loader and parser for ARKSML files using the built in XML parser.

<!--{package-dependencies ./package.json}-->

# Use
## Parsing Raw Annotations
```js
import { ArksmlLoader } from '@gov.nasa.jpl.honeycomb/arksml-loader';

const loader = new ArksmlLoader();
loader.parsers = {
    'CustomAnnotation': node => {
        // ... parse node to object ...
    }
};
loader
    .load('.../path/to/file.arksml')
    .then(result => {

        // ... parsed arksml ...

    });
```

## Parsing Annotations into Frame Data

```js
import { ArksmlLoader } from '@gov.nasa.jpl.honeycomb/arksml-loader';

const loader = new ArksmlLoader();
loader.outputFrames = true;
loader.parsers = {
    'CustomAnnotation': node => {
        // ... parse node to object ...
    }
};
loader
    .load('.../path/to/file.arksml')
    .then(result => {

        // ... parsed arksml ...

    });
```

# API

<!-- START_AUTOGENERATED_DOCS -->
## Functions
### ParserFunction<a name="ParserFunction"></a>

```js
ParserFunction( element : XMLElement ) : Object
```

### parsePosition<a name="parsePosition"></a>

```js
parsePosition( node : XMLElement ) : { x : Number, y : Number, z : Number }
```

Parses a <Position> node with 2 or 3 numbers.

### parseQuaternion<a name="parseQuaternion"></a>

```js
parseQuaternion( node : XMLElement ) : { x : Number, y : Number, z : Number, w : Number }
```

Parses a <Quaternion> node with 4 numbers.

### parseRMCSite<a name="parseRMCSite"></a>

```js
parseRMCSite( node : XMLElement ) : { rmcSite : Number }
```

Parses a node with <RMC_Site> and <RMC_Drive> children.

### parseRectangle<a name="parseRectangle"></a>

```js
parseRectangle(
	node : XMLElement
) : { position : Object, angle : Number, halfWidth : Number, halfHeight : Number }
```

Parses a <Rectangle> node.

### parseTriangle<a name="parseTriangle"></a>

```js
parseTriangle( node : XMLElement ) : { points : Array<Object> }
```

Parses a <Triangle> node.

### parseCircle<a name="parseCircle"></a>

```js
parseCircle( node : XMLElement ) : { position : Object, radius : Number }
```

Parses a <Circle> node.

### parseKeepZone<a name="parseKeepZone"></a>

```js
parseKeepZone(
	node : XMLElement
) : { shape : Object, shapeType : String, keepZoneType : 'in' | out }
```

Parses a <KeepZone> node.

### parseNavGoal<a name="parseNavGoal"></a>

```js
parseNavGoal( node : XMLElement ) : { position : Object, radius : Number }
```

Parse a <NavGoal> node.

### parseArmTarget<a name="parseArmTarget"></a>

```js
parseArmTarget( node : XMLElement ) : { position : Object, quaternion : Object, name : String }
```

Parse a <NavGoal> node.

### parseRoverState<a name="parseRoverState"></a>

```js
parseRoverState( node : XMLElement ) : Object<String, Number>
```

Parse the entire rover state out of an XML node and return an object with key being the name and value being the html content
For example, <Knot Name="ARM_NAMED_TARGET_3_POSE_FULL_Z">0.000000</Knot>
{'ARM_NAMED_TARGET_3_POSE_FULL_Z': 0.0}

### parseImageAcquire<a name="parseImageAcquire"></a>

```js
parseImageAcquire(
	node : XMLElement
) : { camera : String, position : Object, quaternion : Object, roverState : Object }
```

Parse an ImageAcquire block from an XML node
```xml
<ImageAcquire Camera="NAVR">
          <RMC_Site>1</RMC_Site>
          <RMC_Drive>0</RMC_Drive>
          <Position>0.000000 0.000000 0.000000</Position>
          <Quaternion>0.000000 -0.000000 0.000000 1.000000</Quaternion>
          <RoverState>...</RoverState>
</ImageAcquire>
```

## AnnotationData

### type<a name="AnnotationData#type"></a>

```js
type : String
```


The name embedded in the ARKSML file.


## ArksmlResult

### name<a name="ArksmlResult#name"></a>

```js
name : String
```


The name embedded in the ARKSML file.


### spans<a name="ArksmlResult#spans"></a>

```js
spans : Array<{ startTime : Number, endtime : Number, annotations : Array<AnnotationData> }>
```


List of annotation spans within the file.


### events<a name="ArksmlResult#events"></a>

```js
events : Array<{ time : Number, annotations : Array<AnnotationData> }>
```


List event annotation data.


## ArksmlFramesResult

### name<a name="ArksmlFramesResult#name"></a>

```js
name : String
```


The name embedded in the ARKSML file.


### frames<a name="ArksmlFramesResult#frames"></a>

```js
frames : Array<{ time : Number, state : { annotations : Array<AnnotationData> } }>
```


The array of annotations converted to frames. A new frame is inserted every time the
list of relevant annotations change. This includes events.


### events<a name="ArksmlFramesResult#events"></a>

```js
events : Array<{ time : Number, annotations : Array<AnnotationData> }>
```


List event annotation data.


## ArksmlLoader

Extendable class for loading and parsing ARKSML files.

### parsers<a name="ArksmlLoader#parsers"></a>

```js
parsers : Object
```


Dictionary of parsers. By default `ArmTarget`, `Target`, `KeepZone`, `NavGoal`,
and `ImageAcquire` tags are parsed.


### outputFrames<a name="ArksmlLoader#outputFrames"></a>

```js
outputFrames : Boolean = false
```


Whether or not to return the data as a set of frames in an array of the form
```js
[{
    time,
    state: {
        annotations: [...]
    }
}, ...]
```


### eventDuration<a name="ArksmlLoader#eventDuration"></a>

```js
eventDuration : Numbar = 5.0
```


What the minimum duration for events should be when converting to frames.


### minimumDuration<a name="ArksmlLoader#minimumDuration"></a>

```js
minimumDuration : Numbar = 5.0
```


The minimum duration of any given annotation in the file. If an annotaiton is shorter
than this then it is extended from its startTime to this time.


### fetchOptions<a name="ArksmlLoader#fetchOptions"></a>

```js
fetchOptions : Object = { credentials: 'same-origin' }
```


Fetch options for loading the file.


### constructor

```js
constructor( parsers : Object<String, ParserFunction> = {} ) : void
```

Takes a dictionary of parser functions for parsing annotation tags. The parser functions
are keyed based on the name of the annotation tag it should parse.

### load<a name="ArksmlLoader#load"></a>

```js
load( url : String ) : Promise<ArksmlResult | ArksmlFramesResult>
```

Loads and parses the ARKSML file. The promise resolves with the returned
data from the [parse](#ArksmlLoader#parse) function.

### parse<a name="ArksmlLoader#parse"></a>

```js
parse( str : String ) : RKSMLResult
```

Parses the contents of the given ARKSML and returns an object describing
the telemetry.

### preprocessFrames<a name="ArksmlLoader#preprocessFrames"></a>

```js
preprocessFrames(
	rawSpans : Array<{ startTime : Number, endtime : Number, annotations : Array<AnnotationData> }>, 
	rawEvents : Array<{ time : Number, annotations : Array<AnnotationData> }>, 
	name : String
) : void
```

Overrideable function called when we need to preprocess spans and events


<!-- END_AUTOGENERATED_DOCS -->