{"id":20209397,"url":"https://github.com/googlemaps-samples/js-3d-storytelling","last_synced_at":"2025-04-10T13:05:48.956Z","repository":{"id":230051730,"uuid":"742130440","full_name":"googlemaps-samples/js-3d-storytelling","owner":"googlemaps-samples","description":null,"archived":false,"fork":false,"pushed_at":"2024-03-27T14:50:16.000Z","size":19536,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-04-17T18:10:56.920Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://goo.gle/3d-storytelling-admin","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/googlemaps-samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-01-11T20:27:24.000Z","updated_at":"2024-04-15T08:54:02.000Z","dependencies_parsed_at":"2024-03-27T16:23:07.416Z","dependency_job_id":null,"html_url":"https://github.com/googlemaps-samples/js-3d-storytelling","commit_stats":null,"previous_names":["googlemaps-samples/js-3d-storytelling"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googlemaps-samples%2Fjs-3d-storytelling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googlemaps-samples%2Fjs-3d-storytelling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googlemaps-samples%2Fjs-3d-storytelling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googlemaps-samples%2Fjs-3d-storytelling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/googlemaps-samples","download_url":"https://codeload.github.com/googlemaps-samples/js-3d-storytelling/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224573384,"owners_count":17333808,"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":[],"created_at":"2024-11-14T05:39:53.521Z","updated_at":"2024-11-14T05:39:54.040Z","avatar_url":"https://github.com/googlemaps-samples.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 3D Storytelling solution\n\n[3D Storytelling video](https://storage.googleapis.com/3d-solutions-assets/storytelling-1080p-overview.gif)\n\n![](/src/assets/readme-images/storytelling-4k.gif)\n## Overview\nThe 3D Storytelling solution bridges storytelling and mapping, enabling creators to craft immersive and interactive narratives using [Photorealistic 3D Tiles](https://developers.google.com/maps/documentation/tile/3d-tiles-overview).\n\n1. Explore the [hosted admin app](https://goo.gle/3d-storytelling-admin) to build your\nfirst story\n\n2. Download the config once the story is ready\n\n3. Create a fork of this repo and add the downloaded config file as config.json\n\n4. Start the app\n\nThis repository consists of two parts. The Storytelling app and an Admin app which adds a control panel to create new stories.\n\nYou can build a story configuration using the Admin UI and then you can download the config.\nThe demo app uses this config which is loaded from locally to load the story.\n\n## Prerequisits\n\nThe solution leverages Google maps Platform Photorealistic 3D tiles with Cesium.js as the renderer. Enable all the following APIs:\n\n- [Map Tiles API](https://console.cloud.google.com/marketplace/product/google/tile.googleapis.com?utm_source=3d_solutions_storytelling)\n- [Maps JavaScript API](https://console.cloud.google.com/marketplace/product/google/maps-backend.googleapis.com?utm_source=3d_solutions_storytelling)\n- [Places API](https://console.cloud.google.com/marketplace/product/google/places-backend.googleapis.com?utm_source=3d_solutions_storytelling)\n\nYou need to create a [Google API Key](https://console.cloud.google.com/apis/credentials) and restrict it to at least these APIs.\n\nAlso, it is always a good idea to add restrictions for specific websites (i.e. `localhost:5500` for local development).\n\n\n### Quickstart - Static webserver\n\n1. [Download](https://github.com/googlemaps-samples/js-3d-area-explorer/archive/refs/heads/main.zip) or `git clone` this repository\n2. Extract the contents of the `src` folder\n3. Adjust the `config.json` to your needs - see [Configuration](#Configuration)\n4. Add your Google Maps Platform API key to [env.exmaple.js](src/env.exmaple.js) and rename the file to `env.js`\n5. Serve the files with a static webserver\n\n### Quickstart: Start Admin App using build in bash script\n\n1. Clone this repo to your local machine: `git clone ...`\n2. Run the admin setup script: `cd js-3d-area-explorer \u0026\u0026 chmod +x build_admin.sh`\n3. Start the server: `./build_admin.sh \u003cYOUR_GMP_API_KEY\u003e`\n    * Note: The script can pick up the API_KEY from envrionment variable `API_KEY` as well.\n    * Note: The script can also be started as `./build_admin.sh \u003cPORT\u003e \u003cYOUR_GMP_API_KEY\u003e`. By\n    default it starts at port 5500.\n\n## Build using Node.js\n\n### Demo app\n\nYou can  use your own local webserver to show the 3D Area Explorer app like this:\n\n* From the root directory: `npx http-server -p 5500 ./src`\nFor the local development you still need the API key for 3D Map Tiles and Google Places/Maps requests.\n\n## Build using Docker\n\n### Build the Demo App with Docker\n\nYou need to have docker installed to best work with the **demo-app** locally.\n\n1. Clone the repository\n2. `docker-compose build demo`\n3. `docker-compose up demo`\n\n### Build the Admin App with Docker\n\nThere is a second docker compose service `docker-compose up app` which only serves the admin app. For this you may need to update the `config.json` file to include you data.\n\n### Manually build the Admin app\nNote: You should follow these instructions if you want to create your own admin app in a\ndifferent language other than bash.\n\nTo start the local server as **admin app** do the following:\n\n1. Copy the files in demo/src to demo/\n     * Bash command from `/demo` directory: `cp -r ../demo/src ./demo`\n2. In index.html, at the end of the file, it has reference to main.js. Change it to demo/sidebar.js.\n    * Bash command from `/src` directory: `sed -i'.bak' \"s/main.js/demo\\/sidebar.js/g\" index.html`\n3. Start the node app by running npx\n    * Bash commpand from `src` directory: `http-server -p 5500 ./src`\n\n## Configuration\n\nYou can edit the `config.json` file in the `src` directory to change settings. It is also possible to implement your own `loadConfig` function to get configuration from a different file on a different server or to request an API which dynamically returns configuration.\n\nThe SampleConfig folder contains a few pre built configurations.\n\n### Story configuration\n\nThe `properties` object in the `config.json` is responsible for the overall story settings. Here you can set the hero image, title, date, description and inital camera position of the story as a whole.\n\n### Chapter\n\nThe `chapters` property of the config object holds an array of all the story chapters. For each chapter there are different options to set. For example the cahpter title image/video url geo-coordinates and other content. Additionaly you can adjust the camera position and heading (`cameraOptions`), and how to focus the chapter location on the globe (`focusOptions`).\n\n### Camera\n\nThe camera object in the story and chapter properties. The location, where the camera is positioned in the 3D space is configured in the `position` object. The orientation, what the camera is looking at, is set via `heading`, `pitch` and `roll`.\n\n### Cesium / Globe\n\nMost of the cesium setting are located and documented in `/src/utils/cesium.js`.\n\nHere are some highlights:\n\n**RADIUS**: The radius from the target point to position the camera.\n**BASE_PITCH_RADIANS**: The base pitch of the camera. Defaults to -30 degrees in radians.\n**BASE_HEADING_RADIANS**: The base heading of the camera. Defaults to 180 degrees in radians.\n**DEFAULT_HIGHLIGHT_RADIUS**: The default radius size of the highlighted area.\n\n## Local Development\n\nFor the local development you still need the API key for 3D Map Tiles and Google Places/Maps requests.\n\n\n## Deployment\n\nTo deploy the 3D Story telling app you need to upload everything in the `src` folder to a static web server or some other hosting service. A static web server is enough. You need a domain for you webspace, though. Since the Google Maps API key is only restricted on a domain you would risk misuse of the key.\n\nIncluded in the repository is a `Dockerfile` which can be used to build a docker image. This can be used to deploy with Google Cloud Run or other container cloud services.\n\n## Repository structure\n\nThe repositiory is structured to have separate folder for the demo app (`/src`) and the\ndemo/configuration-ui (`/demo/src`). This is due to fact that we need to deploy different versions.\n\nThe app part of the repository is self contained and can be used as is (after updating the configuration). This will show the globe with 3D tiles. Centered on the `location` setting in `config.json`. It will be filled with places from the Google Places API (configured in `config.json`).\n\nThe demo folder contains additional code to render an Admin UI to which helps build a story configuration for `config.json`. The code is added to the deployment by running the `/demo/Dockerfile`.\n\n## Terms of Service\n\nThis solution uses Google Maps Platform services. Use of Google Maps Platform services through this solution is subject to the [Google Maps Platform Terms of Service](https://cloud.google.com/maps-platform/terms).\n\nThis solution is not a Google Maps Platform Core Service. Therefore, the Google Maps Platform Terms of Service (e.g. Technical Support Services, Service Level Agreements, and Deprecation Policy) do not apply to the code in this solution.\n\n## Support\n\nThis solution is offered via an open source license. It is not governed by the Google Maps Platform [Support Technical Support Services Guidelines](https://cloud.google.com/maps-platform/terms/tssg), the [SLA](https://cloud.google.com/maps-platform/terms/sla), or the [Deprecation Policy](https://cloud.google.com/maps-platform/terms) (however, any Google Maps Platform services used by the solution remain subject to the Google Maps Platform Terms of Service).\n\nIf you find a bug, or have a feature request, please [file an issue](https://github.com/googlemaps-samples/js-3d-storytelling/issues) on GitHub. If you would like to get answers to technical questions from other Google Maps Platform developers, ask through one of our [developer community channels](https://developers.google.com/maps/developer-community). If you'd like to contribute, please check the Contributing guide.\n\nYou can also discuss this solution on our Discord server.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglemaps-samples%2Fjs-3d-storytelling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgooglemaps-samples%2Fjs-3d-storytelling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglemaps-samples%2Fjs-3d-storytelling/lists"}