Upgrade Guide
Upgrading to v3.4
WMSService
- thesrs
parameters has been renamed tocrs
in alignment with the most recent WMS 1.3.0 conventions.
Upgrading to v3.2
@loaders.gl/geopackage
- The default data format returned is now
options.gis.format: 'tables'
, which returns the typeTables<ObjectRowTable>
, where thedata
of each table is an array of GeoJSON features. (TheTables
andObjectRowTable
types are exported from@loaders.gl/schema
.) You can useoptions.gis.format: 'geojson'
to return an object mapping table names to an array of GeoJSON features.
Upgrading to v3.0
Platform Support Updates
- Node.js 10 is no longer supported (LTS maintenance of Node.js 10 ended in May 2021).
- The
module
entry point in the published module is no longer transpiled to ES5 as modern JavaScript is supported now support recent evergreen browsers resulting bundle size reduction and better performance. Themain
entry point is still fully transpiled toes5
, you can select this entry point using e.g. themainField
option in webpack.
Worker Concurrency
Default number of worker threads for each loader has been reduced from 5
to 3
on non-mobile devices and to 1
on mobile devices to reduce memory use. Generally, increasing the number of workers has diminishing returns.
@loaders.gl/core
- Passing
fetch
options (such asheaders
) toload()
andparse()
etc. should now be done via theoptions.fetch
options object (e.g.options.fetch.headers
). Specifyingfetch
options on the root options object was deprecated in v2.3 and is no longer supported in v3.0.
@loaders.gl/compression
- The
Transform
API in v2.3 has been replaced withCompression
classes that handle both compression and decompression. Please refer to the documentation.
@loaders.gl/crypto
- The
Transform
API in v2.3 has been replaced withHash
classes that handle both compression and decompression. Please refer to the documentation.
@loaders.gl/csv
- The format of parsed data (i.e. whether table rows are objects or arrays) is now controlled by
options.csv.shape
instead of being dynamically selected based on whether the CSV file has a header row. The defaultshape
is nowobject-row-table
. Default column names are generated if no header row is present. This is a breaking change when loading CSV files without header rows. - Duplicate column names will have a counter suffix added to ensure that they are unique. In rare cases this could be a breaking change.
@loaders.gl/gltf
GLTFScenegraph
is updated to provide modifying capabilities. Signatures of some methods have been changed to use named parameters (rather than positional parameters).- The deprecated
GLBBuilder
class andencodeGLTFSync
functions have now been removed.
@loaders.gl/basis
- Module has been moved to
@loaders.gl/textures
.
@loaders.gl/images
- The texture API
loadImage
,loadImageArray
,loadImageCube
has been moved to the new@loaders.gl/textures
module, and have been renamed toloadImageTexture*
. - The binary image API has been consolidated in a single function
getBinaryImageMetadata()
: - A number of previously deprecated exports have been removed:
Export | Replacement |
---|---|
isBinaryImage(arrayBuffer) | Boolean(getBinaryImageMetadata(arrayBuffer)) |
getBinaryImageMIMEType(arrayBuffer) | getBinaryImageMetadata(arrayBuffer)?.mimeType |
getBinaryImageSize(arrayBuffer) | getBinaryImageMetadata(arrayBuffer)?.{width, height} |
HTMLImageLoader | Use ImageLoader with options {image: type: 'image'} |
getDefaultImageType() | N/A |
getSupportedImageType(imageType?) NA |
@loaders.gl/kml
- The
KMLLoader
,GPXLoader
, andTCXLoader
now require a value foroptions.gis.format
. Previously, the lack of a value would return data in "raw" format, i.e. not normalized to GeoJSON. To return GeoJSON-formatted data, useoptions.gis.format: 'geojson'
. Other options arebinary
andraw
. - The
kml.normalize
option has been deprecated. Whenoptions.gis.format
isgeojson
, coordinates will always be in longitude-latitude ordering.
@loaders.gl/loader-utils
createWorker()
now creates a generic worker. For loader workers use the newcreateLoaderWorker()
function.
@loaders.gl/tiles-3d-loader
- Added
featureIds
attribute to i3s tile content. It is an array of feature ids which specify which feature each vertex belongs to. Can be used for picking functionality.
@loaders.gl/tables
- The (undocumented)
@loaders.gl/tables
module has been renamed to@loaders.gl/schema
.
Upgrading to v2.3
@loaders.gl/core
:
selectLoader()
is now async and returns aPromise
that resolves to a loader.selectLoaderSync()
is available for situations when calling an async function is inconvenient.- Passing
fetch
options toload()
andparse()
etc. should now be done via theoptions.fetch
sub-options object. fetch options on the root object are now deprecated.
@loaders.gl/kml
:
- The
KMLAsGeoJsonLoader
has been removed, useKMLLoader
, withoptions.gis.format: 'geojson'
.
Upgrading to v2.2
@loaders.gl/core
selectLoader
is no longer experimental. If you were using the experimental export, replace_selectLoader
withselectLoader
. Also note that argument order has changed and now aligns withload
andparse
parseInBatchesSync
has been removed, all batched parsing is now performed asynchronously.
Some iterator utilities that are mostly used internally have been changed.
Function | Replacement / Status |
---|---|
makeChunkIterator | combined into makeIterator |
makeStreamIterator | combined into makeIterator |
textDecoderAsyncIterator | makeTextDecoderIterator |
lineAsyncIterator | makeLineIterator |
numberedLineAsyncIterator | makeNumberedLineIterator |
getStreamIterator | Deprecated in 2.1, now removed in 2.2 |
contatenateAsyncIterator | Deprecated in 2.1, now removed in 2.2 |
@loaders.gl/csv
- Header auto-detection now requires
options.csv.header
to be set to'auto'
instead ofundefined
.'auto'
is the new default value for this option, so this change is unlikely to affect applications.
@loaders.gl/json
- The experimental
json._rootObjectBatches
option is now deprecated. Use the top-levelmetadata: true
option instead. Note that thebatchType
names have also changed, see the JSONLoader docs for details.
@loaders.gl/ply
The experimental streaming _PLYStreamingLoader
has been removed. Use the non-streaming PLYLoader
instead.
@loaders.gl/images
The new function getBinaryImageMetadata()
replaces isBinaryImage()
, getBinaryImageSize()
and getBinaryImageMIMEType()
. The old functions are now deprecated, but still available.
Upgrading to v2.1
@loaders.gl/core
Some iterator helper functions have been renamed, the old naming is now deprecated.
Old Name | New Name |
---|---|
getStreamIterator | makeStreamIterator |
contatenateAsyncIterator | concatenateChunksAsync |
@loaders.gl/json
- Experimental exports have been removed
JSONParser
,StreamingJSONParser
,ClarinetParser
.
@loaders.gl/images
The experimental ImageLoaders for individual formats introduced in 2.0 have been removed, use ImageLoader
for all formats.
@loaders.gl/images
getImageData(image)
now returns an object with{data, width, height}
instead of just thedata
array. This small breaking change ensures that the concept of image data is consistent across the API.ImageLoader
:options.image.type
: Thehtml
andndarray
image types are now deprecated and replaced withimage
anddata
respectively.
@loaders.gl/3d-tiles
Tileset3DLoader
and Tile3DLoader
are replaced by Tiles3DLoader
, which supports loading both a 3D tileset file and a tile. Check loaders.gl/3d-tiles
for loaded data format.
Upgrading to v2.0
Version 2.0 is a major release that consolidates functionality and APIs, and a number of deprecated functions have been removed.
Some general changes:
- All exported loader and writer objects now expose a
mimeType
field. This field is not yet used by@loaders.gl/core
but is available for applications (e.g. seeselectLoader
). - All (non-worker) loaders are now required to expose a
parse
function (in addition to any more specializedparseSync/parseText/parseInBatches
functions). This simplifies using loaders without@loaders.gl/core
, which can reduce footprint in small applications.
@loaders.gl/core
Removal | Replacement |
---|---|
TextEncoder | Use global TextEncoder instead and @loaders.gl/polyfills if needed |
TextDecoder | Use global TextDecoder instead and @loaders.gl/polyfills if needed |
createReadStream | fetch().then(resp => resp.body) |
parseFile | parse |
parseFileSync | parseSync |
loadFile | load |
@loaders.gl/images
Removal | Replacement |
---|---|
ImageHTMLLoader | ImageLoader with options.images.format: 'image' |
ImageBitmapLoader | ImageLoader with options.images.format: 'imagebitmap' |
decodeImage | parse(arrayBuffer, ImageLoader) |
isImage | isBinaryImage |
getImageMIMEType | getBinaryImageMIMEType |
getImageSize | getBinaryImageSize |
getImageMetadata | getBinaryImageMIMEType + getBinaryImageSize |
Loader Objects
- Loaders can no longer have a
loadAndParse
method. Remove it, and just make sure you defineparse
on your loaders instead.
@loaders.gl/gltf
The GLTFLoader
now always uses the new v2 parser, and the original GLTFParser
has been removed.
Removal | Replacement |
---|---|
GLBParser | GLBLoader |
GLBBuilder | GLBWriter |
GLTFParser | GLTFLoader |
GLTFBuilder | GLTFWriter |
packBinaryJson | N/A |
unpackBinaryJson | N/A |
Note that automatic packing of binary data (aka "packed JSON" support) was only implemented in the v1 GLTFLoader
and has thus also been removed. Experience showed that packing of binary data for .glb
files is best handled by applications.
GLTFLoader option changes
The foillowing top-level options are deprecated and will be removed in v2.0
Removed Option | Replacement | Descriptions |
---|---|---|
gltf.parserVersion | N/A | No longer needs to be specied, only the new gltf parser is available. |
fetchLinkedResources | gltf.fetchBuffers , gltf.fetchImages | |
fetchImages | gltf.fetchImages | |
createImages | N/A | Images are now always created when fetched |
decompress | gltf.decompressMeshes | Decompress Draco compressed meshes (if DracoLoader available). |
DracoLoader | N/A | Supply DracoLoader to parse , or call registerLoaders(pDracoLoader]) |
postProcess | gltf.postProcess | Perform additional post processing before returning data. |
uri | baseUri | Auto-populated when loading from a url-equipped source |
fetch | N/A | fetch is automatically available to sub-loaders. |
@loaders.gl/draco
Removal | Replacement |
---|---|
DracoParser | DracoLoader |
DracoBuilder | DracoWriter |
Loader Objects
- Loaders no longer have a
loadAndParse
removed. Just defineparse
on your loaders.
Upgrading from v1.2 to v1.3
- As with v1.1,
GLTFLoader
will no longer return aGLTFParser
object in v2.0. A new optionoptions.gltf.parserVersion: 2
is provided to opt in to the new behavior now.
Upgrading from v1.0 to v1.1
A couple of functions have been deprecated and will be removed in v2.0. They now emit console warnings. Start replacing your use of these functions now to remove the console warnings and ensure a smooth future upgrade to v2.0.
Also, Node support now requires installing @loaders.gl/polyfills
before use.
@loaders.gl/core
- Removal: Node support for
fetchFile
now requires importing@loaders.gl/polyfills
before use. - Removal: Node support for
TextEncoder
, andTextDecoder
now requires importing@loaders.gl/polyfills
before use. - Deprecation:
TextEncoder
andTextDecoder
will not be exported fromloaders.gl/core
in v2.0.
@loaders.gl/images
- Removal: Node support for images now requires importing
@loaders.gl/polyfills
before use.
@loaders.gl/gltf
- Deprecation:
GLBParser
/GLBBuilder
- These will be merged into GLTF classes.. - Deprecation:
GLTFParser
/GLTFBuilder
- The newGLTF
class can hold GLTF data and lets application access/modify it. - Deprecation:
GLTFLoader
will no longer return aGLTFParser
object in v2.0. Instead it will return a pure javascript object containing the parse json and any binary chunks. This object can be accessed through theGLTF
class. Setoptions.GLTFParser
tofalse
to opt in to the new behavior now.
v1.0
First official release of loaders.gl.