Chevron Down
Table of Contents
Chevron DownAPI Reference

Loader Object

To be compatible with the parsing/loading functions in @loaders.gl/core such as parse and load, a parser needs to be described by a "loader object" conforming to the following specification.

Loader Object Format v1.0

Common Fields

FieldTypeDefaultDescription
nameStringRequiredShort name of the loader ('OBJ', 'PLY' etc)
extensionStringRequiredThree letter (typically) extension used by files of this format
extensionsString[]RequiredArray of file extension strings supported by this loader
categoryStringOptionalIndicates the type/shape of data
parse | workerFunctionnullEvery non-worker loader should expose a parse function.

Note: Only one of extension or extensions is required. If both are supplied, extensions will be used.

Test Function

FieldTypeDefaultDescription
testFunctionStringString[]
testTextFunctionnullGuesses if a text format file is of this format by examining the first characters in the file

Parser Functions

Each (non-worker) loader should define a parse function. Additional parsing functions can be exposed depending on the loaders capabilities, to optimize for text parsing, synchronous parsing, streaming parsing, etc:

Parser function fieldTypeDefaultDescription
parseFunctionnullAsynchronously parses binary data (e.g. file contents) asynchronously (ArrayBuffer).
parseInBatches (Experimental)FunctionnullParses binary data chunks (ArrayBuffer) to output data "batches"
parseInBatchesSync (Experimental)FunctionnullSynchronously parses binary data chunks (ArrayBuffer) to output data "batches"
parseSyncFunctionnullAtomically and synchronously parses binary data (e.g. file contents) (ArrayBuffer)
parseTextSyncFunctionnullAtomically and synchronously parses a text file (String)
loadAndParseFunctionnullAsynchronously reads a binary file and parses its contents.

Synchronous parsers are more flexible as they can support synchronous parsing which can simplify application logic and debugging, and iterator-based parsers are more flexible as they can support batched loading of large data sets in addition to atomic loading.

You are encouraged to provide the most capable parser function you can (e.g. parseSync or parseToIterator if possible). Unless you are writing a completely new loader from scratch, the appropriate choice often depends on the capabilities of an existing external "loader" that you are working with.