Package com.luciad.fusion.engine

Class ALfnEngineEnvironment

java.lang.Object
com.luciad.fusion.engine.ALfnEngineEnvironment
public abstract class ALfnEngineEnvironment extends Object
An opaque handle to the execution environment for LuciadFusion engine clients. The handle will be interpreted by LuciadFusion and should be closed by the application once all LuciadFusion processing is finished.

The engine environment also provides configuration of the execution environment. The following configurations are provided:

  • data formats, via registration on the environment's composite format
  • directory for storing engine checkpoint files
  • default tile sizes per data type
  • model reference decoder

The environment also provides support for custom data formats:

  • registration on the composite format
  • a model reference decoder is provided, to determine the model reference
  • custom data formats that allow the configuration of the data model name should support the data model name property for creating model decoders that produce models with a provided data model name
  • for optimal processing during fusion, custom data formats should support the buffer property and input stream factory property for creating model decoders

Since:
10.0
See Also:

  • Constructor Details

  • Method Details

    • newInstance

      public static ALfnEngineEnvironment newInstance(ALfnEnvironment aEnvironment)
      Creates a new engine environment that uses the default supported formats. A single engine environment should be created. The environment should be closed when no longer in use.
      Parameters:
      aEnvironment - the core environment.

    • newInstance

      public static ALfnEngineEnvironment newInstance(ALfnEnvironment aEnvironment, Supplier<List<ALfnFormat>> aFormatSupplier)
      Creates a new engine environment that uses the given supported formats. A single engine environment should be created. The environment should be closed when no longer in use.
      Parameters:
      aEnvironment - the core environment.
      aFormatSupplier - the supplier of formats to decode the source assets
      Since:
      2023.1

    • getEnvironment

      public abstract ALfnEnvironment getEnvironment()
      Returns the core environment.
      Returns:
      the core environment used by this engine environment.

    • getCompositeFormat

      public abstract TLfnCompositeFormat getCompositeFormat()
      Returns the composite format that is used by the engine session to decode the source assets. It defines which types of source assets are supported by the fusion engine.

      The format initially has all the supported formats defined by ALfnFormat.createDefaultFormats(ALfnEngineEnvironment) when the environment is created with newInstance(ALfnEnvironment), or newInstance(ALfnEnvironment, Supplier) when the supplier is null. If the supplier is not null the format initially has all the formats provided through the supplier. formats can be removed and additional ones registered. These formats and can be used for registering formats that need to be processed by the fusion engine.

      Returns:
      the composite format

    • getModelReferenceDecoder

      public abstract ILcdModelReferenceDecoder getModelReferenceDecoder()
      Gets the model reference decoder. The default decoder supports WKT, EPSG, RPC and Luciad reference files. The model reference decoder is used by the formats for decoding data.
      Returns:
      the model reference decoder

    • setModelReferenceDecoder

      public abstract void setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder)
      Sets a model reference decoder.
      Parameters:
      aModelReferenceDecoder - a model reference decoder
      See Also:

    • getCheckpointDirectory

      public abstract File getCheckpointDirectory()
      Deprecated.
      This setting is not used anymore. Fusion engine checkpoints are now stored in the coverage user data on the Tile Store. Using null to disable checkpoints is still valid, but instead you should set the checkpoint interval to -1 (you can set it on the session builders for raster or vector data).
      Gets the directory where the engine checkpoints are stored. By default, a location within the user's home directory is used. This directory will be used by the engine.

      The checkpoint directory may be null,

      Returns:
      the checkpoint directory, possibly null

    • setCheckpointDirectory

      public abstract void setCheckpointDirectory(File aCheckpointDirectory)
      Deprecated.
      This setting is not used anymore. Fusion engine checkpoints are now stored in the coverage user data on the Tile Store. Using null to disable checkpoints is still valid, but instead you should set the checkpoint interval to -1 (you can set it on the session builders for raster or vector data).
      Sets the checkpoint directory. The directory does not need to exist, and may even be null.

      When the directory is null, the saving of checkpoints is disabled. There are configurations where this is may be required, depending on three settings:

      1. Saving checkpoints enabled or disabled
      2. Commit policy PER_TILE or PER_COVERAGE (see ALfnTileStore.CommitPolicy)
      3. Produce tiles at all levels or not (see TLfnRasterCoverageMetadata.Builder.levelsToProduce(int[]))
      Currently, not all combinations of these three settings are supported. The limitations are:
      • Saving checkpoints enabled + commit policy PER_COVERAGE commit policy → all levels must be produced. This is currently only supported for raster sessions. Vector sessions always combine all except the most detailed level.
      • Saving checkpoints enabled + not all levels are produced → commit policy must be PER_TILE.
      • Commit policy PER_COVERAGE + not all levels produced → saving of checkpoints must be disabled.
      If saving of checkpoints is enabled while the Tile Store has a per-coverage commit policy and not all levels are set to be produced, fusion may either fail when attempting to resume from checkpoint, or resume using old versions of a tile.
      Parameters:
      aCheckpointDirectory - the new directory for storing checkpoints
      See Also:

    • getEngineThreadCount

      public abstract int getEngineThreadCount()
      Gets the number of threads used by an engine. The default thread count is the number of available processors.
      Returns:
      the thread count

    • setEngineThreadCount

      public abstract void setEngineThreadCount(int aThreadCount)
      Sets the thread count for engines.
      Parameters:
      aThreadCount - the new thread count
      See Also:

    • getDefaultTileSize

      public abstract int getDefaultTileSize(ELfnDataType aDataType)
      Gets the default tile size for a data type.

      The standard tile sizes are 256 for image and 64 for elevation.

      Parameters:
      aDataType - the data type
      Returns:
      the tile size
      See Also:

    • setDefaultTileSize

      public abstract void setDefaultTileSize(ELfnDataType aDataType, int aTileSize)
      Sets the default tile size for a data type.
      Parameters:
      aDataType - the data type
      aTileSize - the tile size
      See Also:

    • close

      public abstract void close() throws IOException, InterruptedException
      Closes this environment and releases all its resources. The resources may include caches, thread pools, file system coverages, etc. This call may block if resources are still in use.

      Note that this does not close the core environment.

      If not closed explicitly, the client environment will automatically be closed on finalize(). This may happen at an undetermined time in the future, if at all. If you have time-dependent code that relies on the client environment being closed at a specific point in time, you should explicitly close it.

      Closing the client environment multiple times does not throw and has the same effect as closing it once.

      Throws:
      IOException - in case of an I/O failure
      InterruptedException - when the closing is interrupted

    • getS63PermitDirectory

      public abstract File getS63PermitDirectory()
      Gets the directory containing all the S-63 permits. The default is "<user.home>/.luciadfusion/Permits/S-63".
      Since:
      2015.0

    • setS63PermitDirectory

      public abstract void setS63PermitDirectory(File aDir)
      Sets the S-63 permit directory on this engine environment. This directory must be an ancestor of the directory containing all the S-63 permits for all the S-63 data. You can also set it using the system property "com.luciad.fusion.engine.s63PermitDirectory".
      • This method has priority over the the system property.
      • The system property has priority over the default.
      • The default is "<user.home>/.luciadfusion/Permits/S-63".

      Setting the S-63 permit directory is a configuration action. All configuration actions must be done before the engine environment is used. If you call this method, you must do so before calling getCompositeFormat(), otherwise an IllegalStateException will be thrown.

      Parameters:
      aDir - The S-63 permit directory, or null to clear the override and fall back to the system property or the default.
      Throws:
      IllegalStateException - If you call this method after you've already started using this engine environment.
      Since:
      2015.0

    • getImagingEngine

      public ALcdImagingEngine getImagingEngine()
      Gets the imaging engine for the environment, which may be null to indicate that fusion should use the default imaging engine.
      Returns:
      the imaging engine for the environment, which may be null
      Since:
      2016.0