|
| 1 | ++++ |
| 2 | +title = "Loading an Image" |
| 3 | +weight = 400 |
| 4 | ++++ |
| 5 | + |
| 6 | +Now that we’ve played with WWT’s background image, let’s load up an image in the |
| 7 | +foreground. Edit the JavaScript code of your `index.html` file to read as |
| 8 | +follows. Once again, changes relative to the previous section are subtly |
| 9 | +highlighted: |
| 10 | +```js,hl_lines=13-14 17-22 |
| 11 | +var script_interface, wwt; |
| 12 | +
|
| 13 | +function init_wwt() { |
| 14 | + const builder = new wwtlib.WWTControlBuilder("wwtcanvas"); |
| 15 | + builder.startRenderLoop(true); |
| 16 | + script_interface = builder.create(); |
| 17 | + script_interface.add_ready(on_ready); |
| 18 | +} |
| 19 | +
|
| 20 | +function on_ready() { |
| 21 | + console.log("WWT is ready!"); |
| 22 | + wwt = wwtlib.WWTControl.singleton; |
| 23 | + script_interface.add_collectionLoaded(on_wtml_loaded); |
| 24 | + script_interface.loadImageCollection("https://data1.wwtassets.org/packages/2023/07_jwst/weic2316a/index.wtml"); |
| 25 | +} |
| 26 | +
|
| 27 | +function on_wtml_loaded() { |
| 28 | + wwt.setForegroundImageByName("Rho Ophiuchi cloud complex"); |
| 29 | + script_interface.setForegroundOpacity(100); |
| 30 | + script_interface.add_arrived(on_arrived); |
| 31 | + wwt.gotoRADecZoom(16.442, -24.385, 1.06, false); |
| 32 | +} |
| 33 | +
|
| 34 | +function on_arrived() { |
| 35 | + wwt.setBackgroundImageByName("PanSTARRS"); |
| 36 | +} |
| 37 | +
|
| 38 | +window.addEventListener("load", init_wwt); |
| 39 | +``` |
| 40 | + |
| 41 | +When you reload your app, you should see WWT zoom in on and load up [a lovely |
| 42 | +JWST image][weic2316a] of ρ Oph: |
| 43 | + |
| 44 | +[weic2316a]: https://esawebb.org/images/weic2316a/ |
| 45 | + |
| 46 | + |
| 47 | + |
| 48 | +Here, the API function |
| 49 | +{{engineapi(p="classes/ScriptInterface.html#loadImageCollection",t="ScriptInterface.loadImageCollection()")}} |
| 50 | +allows us to extend WWT’s built-in corpus of data with additional data sets. We |
| 51 | +register a callback with |
| 52 | +{{engineapi(p="classes/ScriptInterface.html#add_collectionLoaded",t="ScriptInterface.add_collectionLoaded()")}} |
| 53 | +to get notified when the information has been downloaded, at which point we can |
| 54 | +tell the engine to change the foreground to the new image that it has just |
| 55 | +learned about. |
| 56 | + |
| 57 | +<div class="callout callout-note"> |
| 58 | + |
| 59 | +Try changing the opacity setting to, say, 50, to transparently blend the |
| 60 | +foreground on top of the background. |
| 61 | + |
| 62 | +</div> |
| 63 | + |
| 64 | +If you load up the URL used here, |
| 65 | + |
| 66 | +> <https://data1.wwtassets.org/packages/2023/07_jwst/weic2316a/index.wtml> |
| 67 | +
|
| 68 | +you will see that it is another [WTML collection][wtml], which is stored in |
| 69 | +[XML] format. That WTML file, in turn, points at the actual imagery data, which |
| 70 | +have been processed into WWT’s cloud-friendly tiled formats. This two-step |
| 71 | +approach is an important element of WWT’s data model: while the actual data |
| 72 | +files that WWT displays might be large and slow to download, the WTML files that |
| 73 | +tell the engine *about* data are small and efficient. |
| 74 | + |
| 75 | +[wtml]: https://docs.worldwidetelescope.org/data-guide/1/data-file-formats/collections/ |
| 76 | +[XML]: https://en.wikipedia.org/wiki/XML |
| 77 | + |
| 78 | +<div class="callout callout-note"> |
| 79 | + |
| 80 | +Once again, other coding models provide slightly more sophisticated interfaces. |
| 81 | +The |
| 82 | +{{helpersapi(p="classes/WWTInstance.html#loadImageCollection",t="WWTInstance.loadImageCollection()")}} |
| 83 | +and |
| 84 | +{{piniaapi(p="functions/engineStore.html#loadImageCollection",t="engineStore().loadImageCollection()")}} |
| 85 | +APIs return promises that resolve to |
| 86 | +{{engineapi(p="classes/Folder.html",t="Folder")}} objects, which provide direct |
| 87 | +access to the information retrieved from the WTML URL. |
| 88 | + |
| 89 | +</div> |
| 90 | + |
| 91 | +<div class="callout callout-note"> |
| 92 | + |
| 93 | +WWT can overlay more than two images at once if needed: it has a generic system |
| 94 | +for adding visual |
| 95 | +{{piniaapi(p="functions/engineStore.html#md:general-layer-management",t="layers")}}, |
| 96 | +which can be stacked and combined in arbitrary numbers. “Imageset layers” add |
| 97 | +imagery using the same underlying framework as the background/foreground system. |
| 98 | + |
| 99 | +</div> |
| 100 | + |
| 101 | + |
| 102 | +# Getting Data into WWT |
| 103 | + |
| 104 | +These examples are suggesting that WTML files are pretty important to WWT. |
| 105 | +Indeed, they are. The WWT project includes a lot of support tooling to help you |
| 106 | +manage them: |
| 107 | + |
| 108 | +- The [toasty] Python library and CLI tool provide lots of tools for importing |
| 109 | + images into WWT’s formats, including producing appropriate WTML metadata |
| 110 | +- The [wwt_data_formats] Python library and associated `wwtdatatool` CLI program |
| 111 | + provide some lower-level tools for working with various WWT data and file |
| 112 | + formats, including WTML files. |
| 113 | + |
| 114 | +See also the [WWT Data Guide]. |
| 115 | + |
| 116 | +[toasty]: https://toasty.readthedocs.io/ |
| 117 | +[wwt_data_formats]: https://wwt-data-formats.readthedocs.io/ |
| 118 | +[WWT Data Guide]: https://docs.worldwidetelescope.org/data-guide/1/ |
| 119 | + |
| 120 | + |
| 121 | +# Callback Hell |
| 122 | + |
| 123 | +You might note that we’re piling up a lot of callbacks here. We sure are! |
| 124 | +There’s a reason that web developers talk about [callback |
| 125 | +hell](http://callbackhell.com) — this style of programming rapidly becomes very |
| 126 | +hard to scale and maintain. **This is why we strongly recommend avoiding plain |
| 127 | +JavaScript when building complex WWT apps.** More sophisticated models like the |
| 128 | +[Vue component model](@/getting-started/vue-component-model.md), or even the |
| 129 | +[TypeScript model](@/getting-started/bundled-typescript-model.md) with `async` |
| 130 | +syntax, take a bit more effort to learn, but provide much better tools for |
| 131 | +managing the complex timing concerns of modern web apps. |
0 commit comments