{"id":14981216,"url":"https://github.com/jscastro76/threebox","last_synced_at":"2025-10-02T21:30:42.448Z","repository":{"id":40798432,"uuid":"257199282","full_name":"jscastro76/threebox","owner":"jscastro76","description":"A Three.js plugin for Mapbox GL JS, with support for animations and advanced 3D rendering.","archived":false,"fork":true,"pushed_at":"2024-10-31T02:27:23.000Z","size":116530,"stargazers_count":584,"open_issues_count":66,"forks_count":148,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-01-13T12:05:28.364Z","etag":null,"topics":["mapbox-gl-js","three-js"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"peterqliu/threebox","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jscastro76.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-20T07:05:33.000Z","updated_at":"2025-01-12T20:02:50.000Z","dependencies_parsed_at":"2023-02-10T10:15:17.538Z","dependency_job_id":null,"html_url":"https://github.com/jscastro76/threebox","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jscastro76%2Fthreebox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jscastro76%2Fthreebox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jscastro76%2Fthreebox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jscastro76%2Fthreebox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jscastro76","download_url":"https://codeload.github.com/jscastro76/threebox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235043602,"owners_count":18927006,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mapbox-gl-js","three-js"],"created_at":"2024-09-24T14:03:09.481Z","updated_at":"2025-10-02T21:30:41.418Z","avatar_url":"https://github.com/jscastro76.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `Threebox`\n\n![npm](https://img.shields.io/npm/dt/threebox-plugin?style=social)\n![npm](https://img.shields.io/npm/dw/threebox-plugin?style=flat-square)\n[![GitHub release (latest by date)](https://img.shields.io/github/v/release/jscastro76/threebox?style=flat-square)](https://github.com/jscastro76/threebox/releases/)\n[![NPM version](http://img.shields.io/npm/v/threebox-plugin.svg?style=flat-square)](https://www.npmjs.org/package/threebox-plugin)\n[![NPM license](http://img.shields.io/npm/l/threebox-plugin.svg?style=flat-square)](https://www.npmjs.org/package/threebox-plugin)\n\nA **[*Three.js*](https://threejs.org/)** plugin for **[*Mapbox GL JS*](https://docs.mapbox.com/mapbox-gl-js/examples/)** and **[*Azure Maps*](https://azure.microsoft.com/en-us/services/azure-maps/)** using the [`CustomLayerInterface`](https://docs.mapbox.com/mapbox-gl-js/api/properties/#customlayerinterface) feature. Provides convenient methods to manage objects in lnglat coordinates, and to synchronize the map and scene cameras.\n\u003cimg alt=\"threebox\" src=\"docs/gallery.jpg\"\u003e\n\n\u003cbr\u003e\n\n- - -\n## Latest release\n\n![GitHub Release Date](https://img.shields.io/github/release-date/jscastro76/threebox?style=flat-square)  \nLatest  **code release** is [![GitHub release (latest by date)](https://img.shields.io/github/v/release/jscastro76/threebox?style=flat-square)](https://github.com/jscastro76/threebox/releases/), please review the [**Change log**](https://github.com/jscastro76/threebox/blob/master/CHANGELOG.md) for more details.\n\nThreebox is also available as an **nmp package** [![NPM version](http://img.shields.io/npm/v/threebox-plugin.svg?style=flat-square)](https://www.npmjs.org/package/threebox-plugin)  \n\n```js\nnpm i threebox-plugin\n```\n\u003cbr\u003e\n\n- - -\n\n## ONLY in this Threebox fork\n\n|Models built-in \u0026 custom animations |Mouse over/out, Selected, Drag\u0026Drop, Drag\u0026Rotate, Wireframe \n|---------|-----------------------\n|\u003cimg alt=\"threebox\" src=\"https://i.postimg.cc/vTNLLLLn/Animation-Video.gif\" width=\"100%\"\u003e|\u003cimg alt=\"threebox\" src=\"https://i.postimg.cc/3Jjgnvjz/Wireframes.gif\" width=\"100%\" \u003e\n\n|Tooltips using altitude|Optimization of camera perspective and depth\n|----------|-------\n|\u003cimg alt=\"threebox\" src=\"https://i.postimg.cc/wM7DvR8j/Labels-On-Height.gif\" width=\"100%\"\u003e|\u003cimg alt=\"threebox\" src=\"https://i.postimg.cc/zB9nPwcY/Depth.gif\" width=\"100%\"\u003e\n\n|Runtime style change|Optimized performance through cache\n|----------|-------\n|\u003cimg alt=\"threebox\" src=\"https://i.postimg.cc/QMh57yGP/Style-Change.gif\" width=\"100%\"\u003e|\u003cimg alt=\"threebox\" src=\"https://i.postimg.cc/zf2wTYwB/Performance.gif\" width=\"100%\"\u003e\n\n|Customizable FOV|Geojson and Points Extrusions\n|---------|-------\n|\u003cimg alt=\"threebox\" src=\"https://i.postimg.cc/43Lh7vvR/Customizable-FOV.gif\" width=\"100%\"\u003e|\u003cimg alt=\"threebox\" src=\"https://i.postimg.cc/50KqJdKv/extrusions.gif\" width=\"100%\"\u003e\n\n|Sunlight illumination for a given datetime and lnglat|Models built-in shadows and sky layer synced with Sunlight\n|---------|-------\n|\u003cimg alt=\"threebox\" src=\"https://i.postimg.cc/6QnjWSVm/Eiffel-Shadow.gif\" width=\"100%\"\u003e|\u003cimg alt=\"threebox\" src=\"https://i.postimg.cc/63Y7SP6t/SunSki.gif\" width=\"100%\"\u003e\n\n\u003cbr\u003e\n\nOnly in this fork, there is a list of new features implemented on top of the amazing work from [@peterqliu](https://github.com/peterqliu/threebox/):\n- Updated to [**Three.js r132**](https://github.com/mrdoob/three.js/releases/tag/r132).\n- Updated to **Mapbox-gl-js v2.2.0**.\n- Updated to **Azure Maps v2.0.31**.\n- [+20 examples](https://github.com/jscastro76/threebox/tree/master/examples) with all the new features.\n- Support for multiple 3D format objects (FBX, GLTF/GLB, Collada, OBJ/MTL).\n- Support for 3D extruded shapes from [GeoJson](https://geojson.org/) features or points array.\n- Support for CSS2D labels and rich HTML controls through a new LabelManager.\n- Support for CSS2D tooltips/title browser-like and mapbox-like.\n- Support for built-in Raycaster in Object3D and fill-extrusions together.\n- Support for built-in MouseOver/Mouseout, Selected, Drag\u0026Drop, Drag\u0026Rotate, Wireframe in loadedObjects including events.\n- Support for wireframing on any Object3D, removing them from the Raycaster.\n- Support for [GeoJson](https://geojson.org/) standard features format import and export in different layers.\n- Support for Object3D embedded animations, and custom animations on AnimationManager (i.e. embedded animation + translate + rotate).\n- Support for multi-layer and multi-floor design of spaces.\n- Support for built-in shadows and real Sun light positioning for a given datetime and lnglat coords.\n- Support for built-in Mapbox v2 Sky and Terrain layer synced with real Sun light.\n- Support for Non-AABB Non Axes Aligned Bounding Box and real model size, including floor projection. \n- Support for Object3D auto-centering and 9 default anchor positions customizable through adjustments.\n- Support for `setLayerZoomRange` and `setLayoutProperty` on Custom Layers (not available in Mapbox).\n- Support for `removeLayer` considering Object3D.\n- Support for style change through `setStyle` and keeping Object3D.\n- Support for partial and full dispose of Mapbox, Three and Threebox resources and memory.\n- Support for Orthographic view, customizable Perspective FOV and fixed-size Object3D.\n- Optimization of Camera perspective to have Raycast with pixel-precision level and depth sync between Mapbox and Threebox objects.\n- Optimization for loading thousands of objects through cache.\n- Available as [npm package](https://www.npmjs.com/package/threebox-plugin)\n- Check out [change log](https://github.com/jscastro76/threebox/blob/master/CHANGELOG.md) for more detail.\n\n\u003cbr\u003e\n\n- - -\n\n\n## Documentation\n\u003cimg alt=\"threebox\" src=\"docs/soldieranimation.jpg\"\u003e\n\nAll the [**Threebox Documentation**](/docs/Threebox.md) has been completely updated, including all the methods, properties and events implemented in Threebox and objects, but still *'work in progress'* adding better documented examples and images to illustrate Threebox capabilities.\n- [**Using Threebox**](/docs/Threebox.md#using-threebox)\n- [**Loading a 3D Model**](/docs/Threebox.md#loading-a-3d-model)\n- [**Threebox methods**](/docs/Threebox.md#threebox-methods)\n- [**Object methods**](/docs/Threebox.md#object-methods)\n- [**Examples**](/examples/README.md)\n\n\u003cbr\u003e\n\n- - -\n\n## Compatibility/Dependencies\n\n- [**Three.js 132**](https://github.com/mrdoob/three.js/releases/tag/r132). (already bundled into the Threebox build). If desired, other versions can be swapped in and rebuilt [here](https://github.com/jscastro76/threebox/blob/master/src/three.js), though compatibility is not guaranteed.\n- **Mapbox-gl-js v1.11.1. or v.2.0.1**. **Warning**: Despite v1.11.1 still supported, if used, some features from mapbox v.2.0.1 won't be obviously available such as sky layers. \n- **Azure Maps v2.0.31.**\n\n\u003cbr\u003e\n\n- - -\n\n## Getting started\n\nYou can use threebox in three different ways. \n\n#### NPM install\nAdd threebox to your project via **npm package** [![NPM version](http://img.shields.io/npm/v/threebox-plugin.svg?style=flat-square)](https://www.npmjs.org/package/threebox-plugin) :\n```js\nnpm install threebox-plugin\n```   \n\nThen you will need to import Threebox object in your code. Depending your javascript framework this might be different. \n```js \nimport { Threebox } from 'threebox-plugin'; \n```  \nDepending the framework, wrapper or bundler you ar using, try with this:\n```js \nimport { Threebox } from 'threebox-plugin/dist/threebox'; \n```  \n\n\u003cbr/\u003e\n\n#### Use the bundle locally\nDownload the bundle from [`dist/threebox.js`](dist/threebox.js) or [`dist/threebox.min.js`](dist/threebox.min.js) and include it in a `\u003cscript\u003e` tag on your page.  \nIf you want to use styles predefined, add the link to the cascade style sheet, just ensure the `src` and `href` attributes are pointing to relative or absolute url path.  \n```html\n\u003cscript src=\"../dist/threebox.js\" type=\"text/javascript\"\u003e\u003c/script\u003e\n\u003clink href=\"../dist/threebox.css\" rel=\"stylesheet\" /\u003e\n```\n\u003cbr/\u003e\n\n#### Public CDNs\nThreebox can be also used from different public CDNs:  \n\n##### jsdelivr\nThis CDN has the particularity that always requires the version of the package to download individual files.\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/gh/jscastro76/threebox@v.2.2.2/dist/threebox.min.js\" type=\"text/javascript\"\u003e\u003c/script\u003e\n\u003clink href=\"https://cdn.jsdelivr.net/gh/jscastro76/threebox@v.2.2.2/dist/threebox.css\" rel=\"stylesheet\" /\u003e\n```\n\n\u003cbr/\u003e\n\n##### unpkg\nDespite this CDN admits version, if omitted, it will download always the last one published.\n\n```html\n\u003cscript src=\"https://unpkg.com/threebox-plugin/dist/threebox.min.js\" type=\"text/javascript\"\u003e\u003c/script\u003e\n\u003clink href=\"https://unpkg.com/threebox-plugin/dist/threebox.css\" rel=\"stylesheet\" /\u003e\n```\n\nFor an specific version (i.e. v2.2.1) use the followin:\n```html\n\u003cscript src=\"https://unpkg.com/threebox-plugin@2.2.1/dist/threebox.min.js\" type=\"text/javascript\"\u003e\u003c/script\u003e\n\u003clink href=\"https://unpkg.com/threebox-plugin@2.2.1/dist/threebox.css\" rel=\"stylesheet\" /\u003e\n```\n\n\u003cbr/\u003e\n\n#### Test the samples \nSeveral introductory examples are [here](https://github.com/jscastro76/threebox/tree/master/examples).  \nTo run them, create a `config.js` file with your Mapbox-gl-js access token, alongside and in the format of [the template](https://github.com/jscastro76/threebox/blob/master/examples/config_template.js).\n\n\u003cbr\u003e\n\n- - -\n\n## Contributing\n- Clone the [Github repo](https://github.com/jscastro76/threebox/).\n- Build the library with `npm run build` to get the minimized version, or `npm run dev` to get the development version and rebuild continuously as you develop. \n- Both commands will output a bundle in [`dist/`](dist/) folder.\n\n#### Unit tests\nTests live [here](/tests). \n- Build first the test bundle with `npm run test`, this will create [`tests\\threebox-tests-bundle.js`](tests/threebox-tests-bundle.js)  \n- Then in your preferred browser navigate to [`threebox-tests.html`](https://github.com/jscastro76/threebox/blob/master/tests/threebox-tests.html) and check the console for test results.\n\n#### How to build the project in Visual Studio\nSample to get a full build from scratch for Visual Studio:\n- Install [Node.js](https://nodejs.org/en/) \n- Clone the repo and open a new Project using main.js\n- Install / Update the packages browserify, tape, ncp, uglyfy, watchify.\n- Right click on the project at the Solution Explorer \u003e Open Node.js Interactive Window:\n- execute `.npm [ProjectName] init -y`\n- execute `.npm [ProjectName] install`\n- execute `.npm [ProjectName] i`\n- execute `.npm [ProjectName] run dev` or `.npm run build\n`\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjscastro76%2Fthreebox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjscastro76%2Fthreebox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjscastro76%2Fthreebox/lists"}