Class PanoramaModel
- All Implemented Interfaces:
Model,IProjectedImageryModel,AutoCloseable
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
-
Nested Class Summary
Nested Classes -
Method Summary
Modifier and TypeMethodDescriptionvoidaddObserver(IProjectedImageryModelObserver observer) Registers an observer that will be notified of changes to this model.voidaddPanorama(String id, Point location) Adds a panorama at the given location, using the shared structure configured on the builder.voidaddPanorama(String id, Point location, double yaw) Adds a panorama at the given location, using the shared structure configured on the builder.voidaddPanorama(String id, Point location, double yaw, double pitch) Adds a panorama at the given location, using the shared structure configured on the builder.voidaddPanorama(String id, Point location, double yaw, double pitch, double roll) Adds a panorama at the given location, using the shared structure configured on the builder.voidclose()protected voidfinalize()Returns the meta data for this model.List<@NotNull ProjectedImagery> Returns the projections held by this model.static PanoramaModel.BuilderCreates a new builder with the default values.Returns the bounds of this model, if available.queryTile(String projectionId, ProjectionTileCoordinate tile, CancellationToken cancellationToken) Queries a single tile of a single projection.voidremoveObserver(IProjectedImageryModelObserver observer) Unregisters a previously added observer.voidremovePanorama(String projectionId) Removes the panorama with the given ID and notifies observers through onProjectionsChanged.
-
Method Details
-
finalize
protected void finalize() -
close
public void close()- Specified by:
closein interfaceAutoCloseable
-
newBuilder
Creates a new builder with the default values.- Returns:
- the new builder.
-
getModelMetadata
Returns the meta data for this model.- Specified by:
getModelMetadatain interfaceModel- Returns:
- the meta data for this model.
-
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:
queryBoundsin interfaceModel- Returns:
- the bounds of this model, if available.
-
getProjections
Returns the projections held by this model.- Specified by:
getProjectionsin interfaceIProjectedImageryModel- 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#onImageryInvalidatedmust 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.CancellationExceptionto report a canceled request. Any other exception counts as a failed retrieval, after which the tile is never requested again.
- Specified by:
queryTilein interfaceIProjectedImageryModel- Parameters:
projectionId- the identifier of the projection, as returned byProjectedImagery#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
Registers an observer that will be notified of changes to this model.- Specified by:
addObserverin interfaceIProjectedImageryModel- Parameters:
observer- the observer to add. Must not benull.
-
removeObserver
Unregisters a previously added observer.If the given observer was not previously added, this method has no effect.
- Specified by:
removeObserverin interfaceIProjectedImageryModel- 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 throughProjectedImageryLayer#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 throughProjectedImageryLayer#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 throughProjectedImageryLayer#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 throughProjectedImageryLayer#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
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.
-