Asset Compression
In Verge3D, scene files may be compressed using the highly effective LZMA2 compression algorithm, thus allowing to significantly reduce the size of the files. At the same time, LZMA2 offers fast decompression on the browser side. Typical compression rates observed for Verge3D scenes are: 20x for the .gltf files and 6x for the .bin files.
- When Compress Files
- Exporting Compressed Files
- Using Compressed Files
- Checking Your Files
- Code-Based Apps
- Archivers
When Compress Files
Using asset compression is especially recommended in the following cases:
- .gltf/.bin or .glb scene files are relatively big so that the effect from compression is significant in terms of size reduction;
- you expect slow connections and every kilobyte counts;
- the standard server-side GZIP compression is not enabled or not satisfactory, or you don't even have any access to the server to setup GZIP for Verge3D scene files.
Exporting Compressed Files
Verge3D supports loading of scene files compressed in the .xz file format, which incorporates the LZMA2 compression algorithm. To enable creating .xz files automatically upon export, you can simply turn on the corresponding option in the export settings.
Using Compressed Files
The compressed .xz files (for example, my_awesome_app.gltf.xz and my_awesome_app.bin.xz) should appear near the original ones. What is left is to enable loading them in your app. To do this, go to Puzzles...
...and switch to the init tab:Drag out the configure application puzzle from the Initialization category, if it is not already present in the workspace, and turn on the compressed assets checkbox on it:
Finally, click the Save button. That's it!
Checking Your Files
To ensure that your app now actually loads compressed assets, run your app (either from App Manager or from a website where it is deployed). Open the browser console and switch to the Network tab.
Reload your app so that the console starts displaying files from the beginning. Find the scene files in the list - if everything is ok, they should end with .xz.
Alternatively, you can check whether the compressed assets are enabled by using the performance profile feature.
Code-Based Apps
If you don't want to use Puzzles for some reason, follow these steps to enable asset compression for your apps.
Simply change:
const SCENE_URL = 'my_awesome_app.gltf';
to:
const SCENE_URL = 'my_awesome_app.gltf.xz';
in your_awesome_app.js file.
The same applies to .glb and .glb.xz files if they are used instead of .gltf/.bin.
Archivers
Alternatively, you can create .xz files using archive utilities as 7-Zip, XZ Utils or others.
Archiving with external tools is recomended as a time-saving measure for teams working on big projects. You might need to write some batch scripts to archive your assets in automated way.
Verge3D implementation of an .xz decompressor puts some restrictions on compressed files due to optimization purposes, so not every .xz file can be loaded. .tar.xz files are also not supported. Considering this, it's recommended to use settings described below.
Windows
1) A popular file archiver 7-Zip can be used for creating .xz files.
To compress a file you can right click it, and then choose "7-Zip" -> "Add to archive..." - this opens the corresponding dialog window:
The archivation settings should look like this:
- Archive format: xz
- Compression level: any (Normal, Maximum and Ultra give best results)
- Compression method: LZMA2 (the only available option)
- Dictionary size: up to 8 MB - the more the better (more than 8MB is not supported by the engine)
Also you can use a command line version of 7-Zip instead:
7z.exe a -m0=LZMA2:d23 scene.gltf.xz scene.gltf
7z.exe a -m0=LZMA2:d23 scene.bin.xz scene.bin
2) Alternatively, you can use a special command line tool called XZ Utils. Its Windows binaries are available here in the Pre-built binaries section.
The usage is simple:
xz.exe -k -f -6 scene.gltf
xz.exe -k -f -6 scene.bin
Linux
1) A 7-Zip command line port can be available out of the box or from official repositories as a package named p7zip.
The usage is similar to the one in Windows:
7z a -m0=LZMA2:d23 scene.gltf.xz scene.gltf
7z a -m0=LZMA2:d23 scene.bin.xz scene.bin
2) XZ Utils is also available out of the box or from official repositories in most Linux distros.
The usage is similar to the one in Windows:
xz -k -f -6 scene.gltf
xz -k -f -6 scene.bin
macOS
1) A 7-Zip command line port can be installed via
Homebrew as a package named p7zip:
$ brew update
$ brew install p7zip
The usage is the same as in Linux.
2) XZ Utils binaries are available for macOS 10.5+ here in the Pre-built binaries section. The usage is the same as in Linux.
Got Questions?
Feel free to ask on the forums!