Skip to main content

selectSource 🚧

From-v2.2

The selectSource() and selectSourceSync() functions will automatically select an appropriate source for a specific url or Blob. selectSource() is called by the createDataSource() and createDataSourceSync() functions, but can also be called directly from applications.

Source selection heuristics are based on:

  • Filename (or url) extensions
  • MIME types (from Response content-type headers or Blob.type/File.type fields)
  • Initial bytes - for certain inputs, the initial bytes in the supplied data can be compared against known "magic bytes" for various file formats.

Usage

Select a source from a list of provided sources:

import {selectSourceSync} from '@loaders.gl/core';
import {PMTilesSource} from '@loaders.gl/pmtiles';
import {MVTSource} from '@loaders.gl/csv';

selectSourceSync('filename.pmtiles', [PMTilesSource, MVTSource]); // => PMTilesSource

Functions

selectSource(data: String | Blob, ..., sources?: Source[], options?): Promise<Source | null>

Selects an appropriate source for a file from a list of candidate sources by examining the data parameter, looking at URL extension, mimeType ('Content-Type') and/or an initial data chunk.

Parameters:

  • data - data to perform autodetection against
  • sources - can be a single source or an array of sources, or null.
  • options.type - Force selection to a specific type of source (must still be provided in the source list).
  • options.nothrow=false - Return null instead of throwing exception if no source can be found

Returns:

  • A single source (or null if options.nothrow was set and no matching source was found).

Throws:

  • If no matching source was found, and options.nothrow was not set.

Regarding the sources parameter:

  • A single source object will be returned without matching.
  • a null source list will use the pre-registered list of sources.
  • A supplied list of sources will be searched for a matching source.

selectSourceSync(data: Promise<String | Blob>, ..., sources?: Source[], options?: DataSourceOptions): Source | null

Supported Formats

  • strings / non-data urls:
  • strings / data urls: The mime type will be extracted from the data url prologue (if available)
  • fetch Response objects: url and headers.get('Content-Type') fields will be used.
  • File and Blob objects:

Peeking into batched input sources is not supported directly by selectSource:

  • Response: Avoids requesting initial data to make sure the response body is not marked as used.
  • Stream: It is not possible to non-destructively peek into a stream.
  • Iterator/AsyncIterator: it is not possible to peek into an iterator.

Instead use helpers to get access to initialContents and pass it in separately.

MIME types

If the standard MIME types for each format are not precise enough, sources.gl also supports unregistered MIME types. Each source will match the application/x.<id> where the <id> is the documented id of the source, e.g. application/x.ply/application/x.draco/etc ...

Remarks

  • File extensions - An attempt will be made to extract a file extension by stripping away query parameters and base path before matching against known source extensions.
  • Stream autodetection - Currently not well supported.