README updates

CesiumGS · Nov 9, 2022 · 93e5ba0 · 93e5ba0
1 parent aba0323
commit 93e5ba0
Show file tree

Hide file tree

Showing 5 changed files with 94 additions and 40 deletions.
diff --git a/Documentation/OfflineGuide/README.md b/Documentation/OfflineGuide/README.md
@@ -27,3 +27,37 @@ const viewer = new Cesium.Viewer("cesiumContainer", {
   geocoder: false,
 });
 ```
+
+## 3D Tiles, glTF, and other static files
+
+Most other files loaded in CesiumJS, such as 3D Tiles or glTF, are static assets that do not require any server-side operations to load. However, since browsers commonly treat requests to load resources using the `file://` schema as cross-origin requests, it's reccomended that you set up a local server.
+
+1. Download and install [Node.js](https://nodejs.org/en/download/)
+
+2. At the command line, run
+
+   ```sh
+   npm install http-server -g
+   ```
+
+   This will install the 'http-server' app from https://github.com/http-party/http-server globally
+
+3. In the directory that contains the data, run
+
+   ```sh
+   http-server -a localhost -p 8003 --cors=http://localhost:8080/
+   ```
+
+   This will start the server, under the address localhost, using port `8003`. The cors parameter will allow the a CesiumJS app running at port `8080` to access the data from this locally running server.
+
+4. Load files in a CesiumJS app at the served url.
+
+   For example, a local tileset in an `example` directory can now be loaded with the following url:
+
+   ```js
+   var tileset = viewer.scene.primitives.add(
+     new Cesium.Cesium3DTileset({
+       url: "http://localhost:8003/example/tileset.json",
+     })
+   );
+   ```
diff --git a/README.md b/README.md
@@ -1,64 +1,80 @@
-<p align="center">
-<img src="https://github.com/CesiumGS/cesium/wiki/logos/Cesium_Logo_Color.jpg" width="50%" />
-</p>
+# CesiumJS
+
+![Cesium](https://github.com/CesiumGS/cesium/wiki/logos/Cesium_Logo_Color.jpg)
 
 [![Build Status](https://travis-ci.com/CesiumGS/cesium.svg?branch=main)](https://travis-ci.com/CesiumGS/cesium)
 [![npm](https://img.shields.io/npm/v/cesium)](https://www.npmjs.com/package/cesium)
 [![Docs](https://img.shields.io/badge/docs-online-orange.svg)](https://cesium.com/learn/)
 
 CesiumJS is a JavaScript library for creating 3D globes and 2D maps in a web browser without a plugin. It uses WebGL for hardware-accelerated graphics, and is cross-platform, cross-browser, and tuned for dynamic-data visualization.
 
-[CesiumJS Homepage](https://cesium.com/cesiumjs)
+[Examples](https://sandcastle.cesium.com/)
+:earth_africa: [Docs](https://cesium.com/learn/cesiumjs-learn/) :earth_asia: [Website](https://cesium.com/cesiumjs) :earth_americas: [Forum](https://community.cesium.com/)
 
-[CesiumJS Features Checklist](https://github.com/CesiumGS/cesium/wiki/CesiumJS-Features-Checklist)
+## :rocket: Get Started
+
+Visit the [Downloads page](https://cesium.com/downloads/) to download a pre-built copy of CesiumJS.
 
-### :rocket: Get Started
+### npm
 
-Visit the [Downloads page](https://cesium.com/downloads/) or install the [npm package](https://www.npmjs.com/package/cesium):
+If you’re building your application using a module bundler such as Webpack, Parcel, or Rollup, you can install CesiumJS via the [`cesium` npm package](https://www.npmjs.com/package/cesium):
 
 ```sh
-npm install cesium
+npm install cesium --save
+```
+
+```js
+import * as Cesium from "cesium";
+import "cesium/Build/Cesium/Widgets/widgets.css";
+
+const viewer = new CesiumWidgets.Viewer("cesiumContainer");
+```
+
+Or, import individual modules to benefit from tree shaking optmtimizations through most build tools:
+
+```js
+import { Viewer } from "cesium";
+import "cesium/Build/Cesium/Widgets/widgets.css";
+
+const viewer = new Viewer("cesiumContainer");
 ```
 
-Have questions? Ask them on the [community forum](https://community.cesium.com/).
+#### Packages
+
+In addition to the `cesium` package, CesiumJS is also distrubuted as smaller scoped npm packages:
+
+- [`@cesium/engine`](./packages/engine/README.md) - CesiumJS's core, rendering, and data APIs
+- [`@cesium/widgets`](./packages/widgets/README.md) - A widgets library for use with CesiumJS
+
+### CDN
+
+Alternatively, [use a content delivery network (CDN) URL](https://cesium.com/learn/cesiumjs-learn/cesiumjs-quickstart/#import-from-cdn) to embed CesiumJS in an HTML page.
+
+### What next?
+
+See our [Quickstart Guide](https://cesium.com/learn/cesiumjs-learn/cesiumjs-quickstart/) for more information on getting a CesiumJS app up and running.
+
+TODO: Link to build guide/other local development docs
 
 Interested in contributing? See [CONTRIBUTING.md](CONTRIBUTING.md). :heart:
 
-### :snowflake: Mission
+## :snowflake: Mission
 
 Our mission is to create the leading 3D globe and map for static and time-dynamic content, with the best possible performance, precision, visual quality, platform support, community, and ease of use.
 
-### :green_book: License
+## :green_book: License
 
 [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html). CesiumJS is free for both commercial and non-commercial use.
 
-### :earth_americas: Where Does the 3D Content Come From?
+## :earth_americas: Where Does the 3D Content Come From?
 
 CesiumJS can stream 3D content such as terrain, imagery, and 3D Tiles from the commercial [Cesium ion](https://cesium.com/blog/2018/03/01/hello-cesium-ion/)
 platform and other content sources. You are free to use any combination of content sources with CesiumJS that you please.
 Using Cesium ion helps support CesiumJS development. :heart:
 
-### :clap: Featured Demos
-
-<p>
-<a href="https://cesium.com/blog/2018/08/21/cybercity/"><img src="https://images.prismic.io/cesium/2018-08-21-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://apps.agi.com/SatelliteViewer/?Status=Operational"><img src="https://images.prismic.io/cesium/2018-03-29-comspoc-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2018/02/05/historic-pharsalia-cabin-point-cloud/"><img src="https://images.prismic.io/cesium/2018-02-05-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2017/12/12/onesky/"><img src="https://images.prismic.io/cesium/2017-12-12-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2017/11/20/nasa-storm-virtual-globe/"><img src="https://images.prismic.io/cesium/2017-11-20-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2017/11/16/gefs/"><img src="https://images.prismic.io/cesium/2017-11-16-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2019/01/04/norad-tracks-santa/"><img src="https://images.prismic.io/cesium/2019-01-04-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2017/07/23/drcog/"><img src="https://images.prismic.io/cesium/2017-07-23-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://demos.cesium.com/NewYork/"><img src="https://images.prismic.io/cesium/2017-05-05-nyc-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2018/09/27/swisstopo-live/"><img src="https://images.prismic.io/cesium/2018-09-27-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2016/12/12/stk-czml/"><img src="https://images.prismic.io/cesium/2016-12-12-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2016/09/29/contextcapture/"><img src="https://images.prismic.io/cesium/2016-09-29-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2016/04/20/flightradar24/"><img src="https://images.prismic.io/cesium/2016-04-20-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2016/02/03/fodarearth/"><img src="https://images.prismic.io/cesium/2016-02-03-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2015/08/19/mars-trek/"><img src="https://images.prismic.io/cesium/2015-08-19-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2015/07/16/hiroshima-archive/"><img src="https://images.prismic.io/cesium/2015-07-16-cover.jpg" width="30%" /></a>&nbsp;
-<a href="https://cesium.com/blog/2019/06/13/red-bull-x-alps-in-cesium/"><img src="https://images.prismic.io/cesium/2015-10-02-cover.jpg" width="30%" /></a>&nbsp;
-<br/>
-<br/>
-</p>
-<h4><a href="https://cesium.com/blog/categories/userstories">See all demos</a></h4>
+Instructions for serving local data are in the CesiumJS
+[Offline Guide](./Documentation/OfflineGuide/README.md).
+
+## :white_check_mark: Features
+
+[CesiumJS Features Checklist](https://github.com/CesiumGS/cesium/wiki/CesiumJS-Features-Checklist)
diff --git a/package.json b/package.json
@@ -133,7 +133,7 @@
     "build-docs-watch": "gulp buildDocsWatch",
     "eslint": "eslint \"./**/*.js\" \"./**/*.cjs\" \"./**/*.html\" --cache --quiet",
     "make-zip": "gulp makeZip",
-    "markdownlint": "markdownlint \"*.md\" \"Documentation/**/*.md\" --ignore CHANGES.md --ignore README.md --ignore LICENSE.md --ignore packages/engine/LICENSE.md --ignore packages/widgets/LICENSE.md",
+    "markdownlint": "markdownlint \"*.md\" \"Documentation/**/*.md\" --ignore CHANGES.md --ignore \"./**/LICENSE.md\"",
     "release": "gulp release",
     "website-release": "gulp websiteRelease",
     "test": "gulp test",
@@ -158,7 +158,7 @@
       "prettier --write"
     ],
     "*.md": [
-      "markdownlint --ignore CHANGES.md --ignore README.md --ignore LICENSE.md --ignore packages/engine/LICENSE.md --ignore packages/widgets/LICENSE.md",
+      "markdownlint --ignore CHANGES.md --ignore LICENSE.md --ignore packages/engine/LICENSE.md --ignore packages/widgets/LICENSE.md",
       "prettier --write"
     ]
   },

diff --git a/packages/engine/README.md b/packages/engine/README.md
@@ -8,6 +8,8 @@
 
 CesiumJS is a JavaScript library for creating 3D globes and 2D maps in a web browser without a plugin. It uses WebGL for hardware-accelerated graphics, and is cross-platform, cross-browser, and tuned for dynamic-data visualization.
 
+`@cesium/engine` includes cesiumJS's core, rendering, and data APIs. Here you'll find terrain and imagery engines, support for 3D Tiles and 3D models, geometries, and vector data.
+
 [Examples](https://sandcastle.cesium.com/)
 :earth_africa: [Docs](https://cesium.com/learn/cesiumjs-learn/) :earth_asia: [Website](https://cesium.com/cesiumjs) :earth_americas: [Forum](https://community.cesium.com/)
 
@@ -45,7 +47,7 @@ import "@cesium/engine/Source/Widget/CesiumWidget.css";
 const cesiumWidget = new CesiumWidget("cesiumContainer");
 ```
 
-See our [Quickstart Guide](https://cesium.com/learn/cesiumjs-learn/cesiumjs-quickstart/) for more information on getting a Cesium app up and running.
+See our [Quickstart Guide](https://cesium.com/learn/cesiumjs-learn/cesiumjs-quickstart/) for more information on getting a CesiumJS app up and running.
 
 ## Community
 

diff --git a/packages/widgets/README.md b/packages/widgets/README.md
@@ -8,6 +8,8 @@
 
 CesiumJS is a JavaScript library for creating 3D globes and 2D maps in a web browser without a plugin. It uses WebGL for hardware-accelerated graphics, and is cross-platform, cross-browser, and tuned for dynamic-data visualization.
 
+`@cesium/widgets` is a widgets library for use with CesiumJS— including the `CesiumViewer` widget plus widgets for common tasks such as animation, base layer selection and geocoding.
+
 [Examples](https://sandcastle.cesium.com/)
 :earth_africa: [Docs](https://cesium.com/learn/cesiumjs-learn/) :earth_asia: [Website](https://cesium.com/cesiumjs) :earth_americas: [Forum](https://community.cesium.com/)
 
@@ -45,7 +47,7 @@ import "@cesium/widgets/Source/widgets.css";
 const viewer = new Viewer("cesiumContainer");
 ```
 
-See our [Quickstart Guide](https://cesium.com/learn/cesiumjs-learn/cesiumjs-quickstart/) for more information on getting a Cesium app up and running.
+See our [Quickstart Guide](https://cesium.com/learn/cesiumjs-learn/cesiumjs-quickstart/) for more information on getting a CesiumJS app up and running.
 
 ## Community