selectSource 🚧
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 orBlob.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 againstsources
- 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
ifoptions.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
andheaders.get('Content-Type')
fields will be used. File
andBlob
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.