Nishvault / Horizonweft / Panorama guide

Embed a wide panorama with jQuery and Horizonweft

A wide illustration can lose its useful details when squeezed into a narrow page. A pan-and-zoom viewer lets readers inspect a portion of the image and move across it. Horizonweft provides that interaction with a configurable jQuery component, a local studio and portable output.

This guide uses a Ridge study — bounded view built from Quiet Ridge, the included original 3000 × 800 fictional landscape illustration. It contains layered green hills, a small house, trees and a sun. It is not a photograph or a real location. The viewer scrolls a flat image; it does not create a 3D sphere, stitched panorama or virtual tour.

Start with the free preview, then choose the scope you need

Try the free fixed panorama to explore drag, arrow keys and zoom before choosing an integration. You can also download the free preview ZIP under its separate free terms. It contains one fixed scene. It does not include the image studio, configurable jQuery API, project editing or export engine.

The developer package is $19.00 USD, one-time. Applicable taxes calculated at checkout. It includes the configurable plugin, local studio, JSON backup, standalone HTML export, integration examples and setup documentation. The steps below that change images or save projects require that package. No account, hosted service, paid API or npm build is needed to run its supplied customer files locally.

Set up a bounded view of the illustration

Extract the developer ZIP with its folders together. From that extracted folder, use your normal local server, for example python3 -m http.server 8797 --bind 127.0.0.1, then open http://127.0.0.1:8797/app/index.html. The server is a local setup option; do not expose your development directory publicly.

Keep the supplied image for this exercise. Enter these settings in the studio and choose Apply settings:

In bounded mode, heading 0 and 360 represent the left and right limits. The number is an image position, not a geographic compass bearing. Enable looping only when the left and right edges meet convincingly; repetition cannot repair a visible seam in ordinary artwork.

Separate applied settings from the view you navigate

After applying, drag across the image or focus its image stage and use Left/Right. Plus/minus zoom, Up/Down can pan vertically when there is vertical overflow, and Home resets the live view. The available vertical movement depends on the image and frame geometry. Wheel zoom is optional and captures wheel events over the stage only when enabled.

Live navigation does not automatically change the saved start view. Save project and Export HTML use the applied project. Unapplied form edits are also excluded. Once you find a framing you want to keep, choose Use current view as start before saving. For a repeatable backup check, first save the 90/1.5/0.5 baseline. Then navigate to another framing, read the Current view values, capture it and save a second JSON. Confirm its three view values match what you captured.

The original 90/1.5/0.5 values remain the backup baseline until captured or explicitly applied. This distinction helps when you want readers to start at one framing while still letting them explore another.

Save, reopen and inspect the actual output

1. Choose Save project after applying or capturing. The JSON contains the embedded image pixels, natural dimensions and all applied settings.
2. Choose Open project and select the downloaded JSON. Wait for validation, then use Replace working project to accept it. Keep current project cancels the pending replacement. A proposed replacement is not already applied.
3. Revisit the settings and image. Save again if you want a second backup to compare. Keep a downloaded JSON copy because browser draft storage is best effort, especially with large images.
4. Choose Export HTML, open that actual downloaded file, and try its controls. This output embeds the image, jQuery, model, plugin and CSS in one document.

For your own image, choose a PNG, JPEG or WebP you may use. The studio bounds are 12 MB, a maximum of 8192 × 4096 pixels, at most 24 million pixels and a width-to-height ratio from 2 to 8. SVG is not accepted. Replacement files are validated and decoded before the inline replacement choice. Keep a valid backup when trying new material.

Initialize the jQuery viewer in your page

Save the following as ridge-study.html in the extracted developer package root. It refers to the included sample image and runtime files; those files are supplied in the developer package, not the free fixed preview.

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Ridge study — bounded view</title>
<link rel="stylesheet" href="app/viewer.css">
<h1>Ridge study — bounded view</h1>
<div id="ridge-study"></div>
<script src="vendor/jquery-3.7.1.min.js"></script>
<script src="app/core.js"></script>
<script src="app/horizonweft.js"></script>
<script>
jQuery('#ridge-study').horizonweft({
  image: 'assets/quiet-ridge.png',
  title: 'Ridge study — bounded view',
  yaw: 90, zoom: 1.5, vertical: 0.5,
  height: 360, wrap: false, wheel: false
});
</script>
</html>

To change only the live view after initialization, use jQuery('#ridge-study').horizonweft('setView', {yaw: 135, zoom: 2, vertical: 0.4});. The component’s state method returns the current numeric view and readiness. Use different host IDs for separate viewers, and call destroy before reinitializing an existing host. The installation and API guide explains lifecycle limits and local events.

The exact initializer and applied-versus-live workflow were exercised with the current source in local DOM tests, including complete JSON equality and generated HTML execution. Those checks use simulated image/chooser APIs and do not establish new browser rendering, physical touch, pinch gestures or another browser engine. Test the actual downloaded output in the page and viewport where you plan to use it.

Choose a portable document or an integration file

Export HTML is self-contained. Copy integration snippet and Download integration HTML instead use the supplied relative app/ and vendor/ paths. Place the integration file at the package root or adjust those references. If copying is unavailable, use the visible read-only code field or download the integration file. Do not disable an existing site’s content-security policy merely to make inline code run.

The purchaser license permits use and customization in your own personal and commercial projects and sharing finished outputs. It excludes standalone resale or redistribution of the source/editor/plugin package. Preserve jQuery’s separate MIT rights. Documentation is included; guaranteed personal support, an SLA, update schedule or business-result guarantee is not.

Downloaded files contain no measurement adapter. The hosted product and fixed preview use fixed anonymous diagnostic counts that respect Do Not Track and Global Privacy Control and exclude image, project and identity data. Diagnostic counts and an opened checkout form do not establish people, payment or sales. Review embedded image content before sharing files, and use the product page to choose between the free fixed preview and the developer package.