Package com.luciad.models.projectedimagery

Interface IProjectedImageryModel

All Superinterfaces:
Model
All Known Implementing Classes:
PanoramaModel, ProjectedVideoModel
public interface IProjectedImageryModel extends Model
Model interface for projected imagery: single images, live video, and 360-degree panoramas.

A model exposes a set of posed projections and serves their tiles on request. A single access pattern covers every case. The layer lists the projections, requests the tiles it needs, and reacts to change notifications:

Implement this interface to supply projected imagery to a ProjectedImageryLayer, or obtain an implementation from a decoder.

Thread safety is the responsibility of the implementer. queryTile must be thread-safe: LuciadCPillar may call it from any thread. Typically, it will be called on a background thread for initial tile loads, and on the render thread when a projection is invalidated (see IProjectedImageryModelObserver#onImageryInvalidated), for example for every video frame. It is also recommended to make addObserver / removeObserver thread-safe so that the layer can safely subscribe and unsubscribe from any thread.

Related article: Projecting images, video and panoramas onto the map

Since:
2026.1

  • Method Details

    • getProjections

      @NotNull List<@NotNull ProjectedImagery> getProjections()
      Returns the projections held by this model.
      Returns:
      the projections.

    • queryTile

      @NotNull 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.
      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

      void addObserver(@NotNull IProjectedImageryModelObserver observer)
      Registers an observer that will be notified of changes to this model.
      Parameters:
      observer - the observer to add. Must not be null.

    • removeObserver

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

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

      Parameters:
      observer - the observer to remove.