py3dtiles.tilers.base_tiler package#

This package contains all the common files for tilers, especially abstract base classes a tiler must derive.

How to create a tiler?#

You should start by deriving the Tiler class. Please see the documentation below for that.

class py3dtiles.tilers.base_tiler.SharedMetadata[source]#

Bases: ABC

Base class with data that must be shared with worker tiler.

class py3dtiles.tilers.base_tiler.Tiler[source]#

Bases: ABC, Generic[_SharedMetadataT, _TilerWorkerT]

This class is the superclass for all tilers in py3dtilers. It is responsible to instantiate the workers it will use and generate new tasks according to the current state of the conversion.

It will receive messages both from its workers and the main process (see process_message).

Its role is to organize tasks to be dispatched to the worker it has constructed and later, to write the tileset corresponding to the hierarchy of tiles it created.

Implementation notice:

  • the name class attribute should be changed by each subclass

  • __init__ should not read any files on the disk, initialize on the other hand is expected to gather metadata for input files

  • as this class is generic over the type of SharedMetadata and TilerWorker, subclassing these 2 classes is also needed when creating a Tiler

  • modifications to the SharedMetadata instance will not be transmitted to other processes, initialize it in initialize and don’t mutate it afterwards

  • all mutable data and parameters must be passed as messages between tilers and workers. Workers will send messages by using yield (see py3dtiles.tilers.base_tiler.tiler_worker.TilerWorker)

  • the constructor of a Tiler is not expected to do any real work. The initialize method on the other hand, should gather metadata from input files

This class will organize the different tasks and their order of dispatch to the TilerWorker instances. When creating a subclass of Tiler, you’re supposed to subclass SharedMetadata and TilerWorker as well.

benchmark(benchmark_id: str, startup: float) → None[source]#

Prints benchmark info at the end of the conversion of this tiler and the writing of the tileset.

abstract get_tasks() → Iterator[tuple[bytes, list[bytes]]][source]#

Yields tasks to be sent to workers.

This methods will get called by the main convert function each time it wants new tasks to be fed to workers. Implementors should each time returns the task that has the biggest priority.

py3dtiles will iterate until the returned iterator is exhausted before continuing the process. It will call it as many times as needed during the execution. It is therefore not necessary to generate all the tasks in one go.

Once this function returns an empty list and all the workers are idle, the conversion process stops.

If generating the tasks is somewhat expensive, do return a Generator instead. Tasks will be sent to workers as soon as they are yielded.

abstract get_tileset(use_process_pool: bool = True) → TileSet[source]#

Get the tileset file once the binary data are written.

This function will be called once by convert after this tiler has stopped generating tasks and all the workers are idle.

Parameters:

use_process_pool – allow the use of a process pool. Process pools can cause issues in

environment lacking shared memory.

abstract get_worker() → _TilerWorkerT[source]#

Returns an instantiated tiler worker.

abstract initialize(files: list[Path], working_dir: Path, out_folder: Path) → None[source]#

This method will be called first by convert to initialize the conversion process. Tilers will receive all the paths informations as argument to this method. Only files supported by this tiler will be in the files argument. Tilers are expected to gather metadata from those input files so that subsequent call to get_tasks can generate some conversion work to do by workers.

This method is probably a good place to init the SharedMetadata subclass instance as well.

memory_control() → None[source]#

Method called at the end of each loop of the convert method. Checks if there is no too much memory used by the tiler and do actions in function

name = b''#
print_summary() → None[source]#

Prints the summary of the tiler before the start of the conversion.

abstract process_message(message_type: bytes, content: list[bytes]) → None[source]#

This method is called with each message sent by workers. Its role is to process those messages, to update the internal state of the tiler, so that new tasks or a tileset writing could proceed.

shared_metadata: _SharedMetadataT#
abstract supports(file: Path) → bool[source]#

This function tells the main process if this tiler supports this file or not.

The main process will use the first supporting tiler it finds for each file.

Implementation should not require to read the whole file to determine if this tiler supports it. In other word, the execution time should be a constant regardless of the file size.

validate() → None[source]#

Checks if the state of the tiler or the binary data written is correct. This method is called after the end of the conversion of this tiler (but before writing the tileset). Overwrite this method if you wish to run some validation code for the generated tileset.

class py3dtiles.tilers.base_tiler.TilerWorker(shared_metadata: _SharedMetadataT)[source]#

Bases: ABC, Generic[_SharedMetadataT]

abstract execute(command: bytes, content: list[bytes]) → Iterator[Sequence[bytes]][source]#

Executes a command sent by the tiler. Each sequence of bytes returned by the returned Iterator will be sent back to the corresponding tiler.

The easiest way to do so is to yield the Sequence to be sent. This will automatically turn the method into a generator, which is incidentally an Iterator. This has the good additional side-effect of passing back control to the calling method, which will in turn send the message immediately, without waiting for this method to be executed.

Implementing classes can use any message format they like provided it is a Sequence of bytes. The only restriction is that the first element of the sequence should not be a value in the py3dtiles.tilers.base_tiler.message_type.WorkerMessageType enum, as those are used internally by the convert process to manage the lifecycles of the different entities.

Submodules#