Class PanoramaModel

java.lang.Object
com.luciad.models.projectedimagery.PanoramaModel
All Implemented Interfaces:
Model, IProjectedImageryModel, AutoCloseable

public final class PanoramaModel extends Object implements AutoCloseable, IProjectedImageryModel
A ready-to-use IProjectedImageryModel for static 360-degree panoramas of which the tiles are served from a URL.

Configure the model with a URL pattern and a shared tile structure, then add panorama positions with addPanorama. The model resolves each tile request to a URL and fetches the image, so a panorama dataset served over HTTP (or from local files) needs no custom IProjectedImageryModel implementation.

Display the panoramas by adding the model to a ProjectedImageryLayer and selecting one or more panoramas by their ID with ProjectedImageryLayer#setSelectedProjections, for example layer->setSelectedProjections({{"entrance", 1.0f}}). Selecting several panoramas at once blends them by weight, which for example lets a navigation controller cross-fade from one panorama to the next.

The URL pattern supports the placeholders {id}, {face}, {level} (or {z}), {x}, {y} and {-y}, for example "https://example.com/{id}/{face}/{level}/{x}_{y}.jpg". Use {-y} instead of {y} for tiling structures with row coordinates running in the opposite direction. For full control over the URL, provide a IPanoramaTileUrlProvider through the builder.

By default the model fetches tiles over HTTP or from the file system, based on the URL scheme. To customize HTTP requests, such as adding authentication headers, provide a IHttpClient through the builder. For full control over fetching, including non-HTTP schemes, provide a IDataLoader instead. Imagery is fetched on demand and is not cached by the model.

LuciadCPillar decodes each fetched tile. JPEG, PNG, TIFF and WebP tiles are supported. A tile that cannot be decoded is reported as an error.

Unless an override is set through PanoramaModel.Builder#bounds, the model's bounds follow the panoramas: they are recomputed on every added or removed panorama as the bounds of all panorama locations, padded with a margin.

All methods are safe to call from any thread.

Since:
2026.1
  • Method Details

    • finalize

      protected void finalize()
      Overrides:
      finalize in class Object
    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
    • newBuilder

      @NotNull public static PanoramaModel.Builder newBuilder()
      Creates a new builder with the default values.
      Returns:
      the new builder.
    • getModelMetadata

      @NotNull public ModelMetadata getModelMetadata()
      Returns the meta data for this model.
      Specified by:
      getModelMetadata in interface Model
      Returns:
      the meta data for this model.
    • queryBounds

      @Nullable public Bounds queryBounds()
      Returns the bounds of this model, if available.

      When the bounds of this model are not known, or if they are too expensive to calculate, this method may return no bounds.

      Specified by:
      queryBounds in interface Model
      Returns:
      the bounds of this model, if available.
    • getProjections

      @NotNull public List<@NotNull ProjectedImagery> getProjections()
      Returns the projections held by this model.
      Specified by:
      getProjections in interface IProjectedImageryModel
      Returns:
      the projections.
    • queryTile

      @NotNull public ProjectionTileQueryResult queryTile(@NotNull String projectionId, @NotNull ProjectionTileCoordinate tile, @NotNull CancellationToken cancellationToken) throws IOException
      Queries a single tile of a single projection.

      This method must be thread-safe. It may be called on a background thread, for example for an initial tile load, but also on the render thread, for example when a projection is invalidated. A projection that fires IProjectedImageryModelObserver#onImageryInvalidated must serve its tiles cheaply and synchronously. Honor the cancellation token for long-running work.

      The possible outcomes are not interchangeable, because each one decides whether the tile is ever requested again:

      • A result holding an image supplies the tile.
      • A result without an image means the tile does not exist, and that tile is not requested again.
      • A failed retrieval also stops the tile from being requested again.
      • A canceled request is the only outcome that leaves the tile eligible for a later request. Throw a java.util.concurrent.CancellationException to report a canceled request. Any other exception counts as a failed retrieval, after which the tile is never requested again.
      Specified by:
      queryTile in interface IProjectedImageryModel
      Parameters:
      projectionId - the identifier of the projection, as returned by ProjectedImagery#getId.
      tile - the coordinate of the requested tile.
      cancellationToken - a token that signals when the result is no longer needed.
      Returns:
      the tile result, or a result without an image when the tile does not exist.
      Throws:
      IOException - when the tile could not be retrieved.
    • addObserver

      public void addObserver(@NotNull IProjectedImageryModelObserver observer)
      Registers an observer that will be notified of changes to this model.
      Specified by:
      addObserver in interface IProjectedImageryModel
      Parameters:
      observer - the observer to add. Must not be null.
    • removeObserver

      public void removeObserver(@NotNull IProjectedImageryModelObserver observer)
      Unregisters a previously added observer.

      If the given observer was not previously added, this method has no effect.

      Specified by:
      removeObserver in interface IProjectedImageryModel
      Parameters:
      observer - the observer to remove.
    • addPanorama

      public void addPanorama(@NotNull String id, @NotNull Point location, double yaw, double pitch, double roll) throws IllegalArgumentException
      Adds a panorama at the given location, using the shared structure configured on the builder.

      Notifies observers through onProjectionsChanged. To replace an existing panorama, remove it first with removePanorama.

      Parameters:
      id - a stable identifier, used for the {id} URL placeholder and to select the panorama through ProjectedImageryLayer#setSelectedProjections. When the default URL pattern is used, it is inserted into the tile URL verbatim, so it should be URL-safe.
      location - the geo-referenced panorama position.
      yaw - rotation around the vertical axis, in degrees.
      pitch - rotation around the lateral axis, in degrees. Positive values tilt down.
      roll - rotation around the longitudinal axis, in degrees.
      Throws:
      IllegalArgumentException - when a panorama with the given id already exists.
    • addPanorama

      public void addPanorama(@NotNull String id, @NotNull Point location, double yaw, double pitch) throws IllegalArgumentException
      Adds a panorama at the given location, using the shared structure configured on the builder.

      Notifies observers through onProjectionsChanged. To replace an existing panorama, remove it first with removePanorama.

      Parameters:
      id - a stable identifier, used for the {id} URL placeholder and to select the panorama through ProjectedImageryLayer#setSelectedProjections. When the default URL pattern is used, it is inserted into the tile URL verbatim, so it should be URL-safe.
      location - the geo-referenced panorama position.
      yaw - rotation around the vertical axis, in degrees.
      pitch - rotation around the lateral axis, in degrees. Positive values tilt down.
      Throws:
      IllegalArgumentException - when a panorama with the given id already exists.
    • addPanorama

      public void addPanorama(@NotNull String id, @NotNull Point location, double yaw) throws IllegalArgumentException
      Adds a panorama at the given location, using the shared structure configured on the builder.

      Notifies observers through onProjectionsChanged. To replace an existing panorama, remove it first with removePanorama.

      Parameters:
      id - a stable identifier, used for the {id} URL placeholder and to select the panorama through ProjectedImageryLayer#setSelectedProjections. When the default URL pattern is used, it is inserted into the tile URL verbatim, so it should be URL-safe.
      location - the geo-referenced panorama position.
      yaw - rotation around the vertical axis, in degrees.
      Throws:
      IllegalArgumentException - when a panorama with the given id already exists.
    • addPanorama

      public void addPanorama(@NotNull String id, @NotNull Point location) throws IllegalArgumentException
      Adds a panorama at the given location, using the shared structure configured on the builder.

      Notifies observers through onProjectionsChanged. To replace an existing panorama, remove it first with removePanorama.

      Parameters:
      id - a stable identifier, used for the {id} URL placeholder and to select the panorama through ProjectedImageryLayer#setSelectedProjections. When the default URL pattern is used, it is inserted into the tile URL verbatim, so it should be URL-safe.
      location - the geo-referenced panorama position.
      Throws:
      IllegalArgumentException - when a panorama with the given id already exists.
    • removePanorama

      public void removePanorama(@NotNull String projectionId)
      Removes the panorama with the given ID and notifies observers through onProjectionsChanged.

      Has no effect if no such panorama exists.

      Parameters:
      projectionId - the identifier of the panorama to remove.