diff --git a/Documentation/Doxygen/DataAssembly.md b/Documentation/Doxygen/DataAssembly.md
deleted file mode 100644
index 9cd2d733ad2aa97874108c81c780f721af721220..0000000000000000000000000000000000000000
--- a/Documentation/Doxygen/DataAssembly.md
+++ /dev/null
@@ -1,108 +0,0 @@
-# Data Assembly
-
-VTK 10.0 introduces a new mechanism for representing data hierarchies
-using vtkPartitionedDataSetCollection and vtkDataAssembly. This document
-describes the design details.
-
-## Data Model
-
-The design is based on three classes:
-
-* `vtkPartitionedDataSet` is a collection of datasets (not to be confused with
- `vtkDataSet`).
-* `vtkPartitionedDataSetCollection` is a collection of `vtkPartitionedDataSet`s.
-* `vtkDataAssembly` defines the hierarchical relationships between items in a
- `vtkPartitionedDataSetCollection`.
-
-### Partitioned Dataset
-
-`vtkPartitionedDataSet` is simply a collection of datasets that are to be
-treated as a logical whole. In data-parallel applications, each dataset may
-represent a partition of the complete dataset on the current worker process,
-rank, or thread. Each dataset in a `vtkPartitionedDataSet` is called a
-**partition**, implying it is only a part of a whole.
-
-All non-null partitions have similar field and attribute arrays. For example, if
-a `vtkPartitionedDataSet` comprises of `vtkDataSet` subclasses, all will have
-exactly the same number of point data/cell data arrays, with same names, same
-number of components, and same data types.
-
-### Partitioned Dataset Collection
-
-`vtkPartitionedDataSetCollection` is a collection of `vtkPartitionedDataSet`.
-Thus, it is simply a mechanism to group multiple `vtkPartitionedDataSet`
-instances together. Since each `vtkPartitionedDataSet` represents a whole dataset
-(not be confused with `vtkDataSet`), we can refer to each item in a
-`vtkPartitionedDataSetCollection` as a **partitioned-dataset**.
-
-Unlike items in the `vtkPartitionedDataSet`, there are no restrictions of consistency
-between each items, partitioned-datasets, in the `vtkPartitionedDataSetCollection`.
-Thus, in the multiblock-dataset parlance, each item in this collection can be thought
-of as a block.
-
-### Data Assembly
-
-`vtkDataAssembly` is a means to define an hierarchical organization of items in a
-`vtkPartitionedDataSetCollection`. This is literally a tree made up of named nodes.
-Each node in the tree can have associated dataset-indices. For a `vtkDataAssembly` is
-associated with a `vtkPartitionedDataSetCollection`, each of the
-dataset-indices is simply the index of a partitioned-dataset in the
-`vtkPartitionedDataSetCollection`. A dataset-index can be associated with multiple nodes in
-the assembly, however, a dataset-index cannot be associated with the same node more than once.
-
-An assembly provides an ability to define a more complex view of the raw data blocks in
-a more application-specific form. This is not much different than what could be achieved using simply
-a `vtkMultiBlockDataSet`. However, there are several advantages to this separation of storage
-(`vtkPartitionedDataSetCollection`) and organization (`vtkDataAssembly`). These will become clear as
-we cover different use-cases.
-
-While nodes in the data-assembly have unique ids, public facing algorithm APIs should not use them. For example
-an extract-block filter that allows users to choose which blocks (rather partitioned-datasets)
-to extract from vtkPartitionedDataSetCollection can expose an API that lets users provide
-path-expression to identify nodes in the associated data-assembly using their names.
-
-Besides accessing nodes by querying using their names, `vtkDataAssembly` also
-supports a mechanism to iterate over all nodes in depth-first or breadth-first
-order using a *visitor*. vtkDataAssemblyVisitor defines a API that can be
-implemented to do custom action as each node in the tree is visited.
-
-## Design Implications
-
-1. Since `vtkPartitionedDataSet` is simply parts of a whole, there is no specific significance
- to the number of partitions. In distributed pipelines, for example, a `vtkPartitionedDataSet`
- on each rank can have arbitrarily many partitions. Furthermore, filters can add/remove
- partitions as needed. Since the `vtkDataAssembly` never refers to individual partitions, this has no
- implication to filters that use the hierarchical relationships.
-
-2. When constructing `vtkPartitionedDataSetCollection` in distributed data-parallel cases,
- each rank should have exactly the same number of partitioned-datasets.
- In this case, each `vtkPartitionedDataSet` at a specific index across all ranks together is
- treated as a whole dataset. Similarly, the `vtkDataAssembly` on each should be identical.
-
-3. When developing filters, it is worth considering whether the filter really is a
- `vtkPartitionedDataSetCollection` filter or simply a `vtkPartitionedDataSet`-aware
- filter that needs to operate on each `vtkPartitionedDataSet` individually. For example,
- typical multiblock-aware filters like ghost-cell-generation, data-redistribution, etc.,
- are simply `vtkPartitionedDataSet` filters. For `vtkPartitionedDataSet`-only filters,
- when the input is a `vtkPartitionedDataSetCollection`, the executive takes care of looping
- over each of the partitioned-dataset in the collection, thus simplifying the filter development.
-
-4. Filters that don't change the number of partitioned-datasets in a
- vtkPartitionedDataSetCollection don't generally affect the relationships
- between the partitioned-datasets and hence can largely pass through the
- vtkDataAssembly. Only filter like extract-block that remove
- partitioned-datasets need to update the vtkDataAssembly. There too,
- vtkDataAssembly provides several convenience methods to update the tree with
- ease.
-
-5. It is possible to develop a mapper that uses the `vtkDataAssembly`. Using
- APIs that let users use path-queries to specify rendering properties for
- various nodes, the mapper can support use-cases where the input structure
- keeps changing but the relationships remain largely intact.
- Since the same dataset-index can be associated with multiple nodes in a
- `vtkDataAssembly`, the mapper can effectively support scene-graph like
- capabilities where user can specify transforms, and other rendering
- parameters, while reusing the heavy datasets. The mapper can easily tell if
- a dataset has already been uploaded to the rendering pipeline since it will
- have the same id and indeed be the same instance even if is being visited
- through different branches in the tree.
diff --git a/Documentation/Doxygen/IOLegacyInformationFormat.md b/Documentation/Doxygen/IOLegacyInformationFormat.md
deleted file mode 100644
index fcafbf6b8374b6e9a4a9f3c7c4b01e5936742f31..0000000000000000000000000000000000000000
--- a/Documentation/Doxygen/IOLegacyInformationFormat.md
+++ /dev/null
@@ -1,164 +0,0 @@
-# VTK Legacy Reader/Writer Information Format
-
-## Overview
-
-The legacy vtk data file readers / writers store certain `vtkInformation`
-entries that are set on `vtkAbstractArray`'s `GetInformation()` object. Support
-is currently limited to numeric and string information keys, both single- and
-vector-valued. Only the information objects attached to arrays are encoded.
-
-## Array Metadata Blocks
-
-A block of metadata may immediately follow the specification of an array.
-Whitespace is permitted between the array data and the opening `METADATA` tag.
-The metadata block is terminated by an empty line.
-
-```
-# vtk DataFile Version 4.1
-vtk output
-ASCII
-DATASET UNSTRUCTURED_GRID
-POINTS 6 float
-0 0 0 1 0 0 0.5 1 0
-0.5 0.5 1 0.5 -1 0 0.5 -0.5 1
-
-METADATA
-COMPONENT_NAMES
-X%20coordinates
-Y%20coordinates
-Z%20coordinates
-INFORMATION 8
-NAME Double LOCATION TestKey
-DATA 1
-NAME DoubleVector LOCATION TestKey
-DATA 3 1 90 260
-NAME IdType LOCATION TestKey
-DATA 5
-NAME String LOCATION TestKey
-DATA Test%20String!%0ALine2
-NAME Integer LOCATION TestKey
-DATA 408
-NAME IntegerVector LOCATION TestKey
-DATA 3 1 5 45
-NAME StringVector LOCATION TestKey
-DATA 3
-First
-Second%20(with%20whitespace!)
-Third%20(with%0Anewline!)
-NAME UnsignedLong LOCATION TestKey
-DATA 9
-
-CELLS 3 15
-4 0 1 2 3
-4 0 4 1 5
-4 5 3 1 0
-
-CELL_TYPES 3
-10
-10
-10
-
-CELL_DATA 3
-FIELD FieldData 1
-vtkGhostType 1 3 unsigned_char
-0 1 1
-METADATA
-COMPONENT_NAMES
-Ghost%20level%20information
-INFORMATION 1
-NAME UNITS_LABEL LOCATION vtkDataArray
-DATA radians
-
-```
-
-As shown, a metadata block can have two sections, `COMPONENT_NAMES` and
-`INFORMATION`. The `INFORMATION` tag is followed by the number of information
-keys that follow.
-
-### COMPONENT_NAMES
-
-If the `METADATA` block contains the line `COMPONENT_NAMES`, the following lines
-are expected to be encoded strings containing the names of each component. There
-must be one line per component.
-
-### INFORMATION
-
-If the `METADATA` block contains the line `INFORMATION`, the number of information
-keys is read from the INFORMATION line and `vtkInformation` data that follows is
-parsed. The general form of a single valued information entry is:
-
-```
-NAME [key name] LOCATION [key location (e.g. class name)]
-DATA [value]
-```
-
-A vector information key is generally represented as:
-
-```
-NAME [key name] LOCATION [key location (e.g. class name)]
-DATA [vector length] [value0] [value1] [value2] ...
-```
-
-The exception is a string vector, which contains encoded entries separated by
-newlines.
-
-Specific examples of supported key types:
-
-#### vtkInformationDoubleKey
-
-```
-NAME Double LOCATION TestKey
-DATA 1
-```
-
-#### vtkInformationDoubleVectorKey
-
-```
-NAME DoubleVector LOCATION TestKey
-DATA 3 1 90 260
-```
-
-#### vtkInformationIdTypeKey
-
-```
-NAME IdType LOCATION TestKey
-DATA 5
-```
-
-#### vtkInformationStringKey
-
-```
-NAME String LOCATION TestKey
-DATA Test%20String!%0ALine2
-```
-
-#### vtkInformationIntegerKey
-
-```
-NAME Integer LOCATION TestKey
-DATA 408
-```
-
-#### vtkInformationIntegerVectorKey
-
-```
-NAME IntegerVector LOCATION TestKey
-DATA 3 1 5 45
-```
-
-#### vtkInformationStringVectorKey
-
-```
-NAME StringVector LOCATION TestKey
-DATA 3
-First
-Second%20(with%20whitespace!)
-Third%20(with%0Anewline!)
-```
-
-#### vtkInformationUnsignedLongKey
-
-```
-NAME UnsignedLong LOCATION TestKey
-DATA 9
-```
diff --git a/Documentation/Doxygen/IOXMLInformationFormat.md b/Documentation/Doxygen/IOXMLInformationFormat.md
deleted file mode 100644
index 7bf63ef2996ad4c824b1d49e8e0f3abbec81cb3b..0000000000000000000000000000000000000000
--- a/Documentation/Doxygen/IOXMLInformationFormat.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# VTK XML Reader/Writer Information Format
-
-## Overview
-
-The vtk xml data file readers / writers store certain `vtkInformation`
-entries that are set on `vtkAbstractArray`'s `GetInformation()` object. Support
-is currently limited to numeric and string information keys, both single- and
-vector-valued. Only the information objects attached to arrays are written/read.
-
-## Array Information
-
-Array information is embedded in the `<DataArray>` XML element as a series of
-`<InformationKey>` elements. The required attributes `name` and `location`
-specify the name and location strings associated with the key -- for instance,
-the `vtkDataArray::UNITS_LABEL()` key has `name="UNITS_LABEL"` and
-`location="vtkDataArray"`. The `length` attribute is required for vector keys.
-
-```{code-block} xml
-:force: true
-<DataArray [...]>
- <InformationKey name="KeyName" location="KeyLocation" [ length="N" ]>
- [...]
- </InformationKey>
- <InformationKey [...]>
- [...]
- </InformationKey>
- [...]
-</DataArray>
-```
-
-Specific examples of supported key types:
-
-### vtkInformationDoubleKey
-
-```xml
-<InformationKey name="Double" location="XMLTestKey">
- 1
-</InformationKey>
-```
-
-### vtkInformationDoubleVectorKey
-
-```xml
-<InformationKey name="DoubleVector" location="XMLTestKey" length="3">
- <Value index="0">
- 1
- </Value>
- <Value index="1">
- 90
- </Value>
- <Value index="2">
- 260
- </Value>
-</InformationKey>
-```
-
-### vtkInformationIdTypeKey
-
-```xml
-<InformationKey name="IdType" location="XMLTestKey">
- 5
-</InformationKey>
-```
-
-### vtkInformationStringKey
-
-```xml
-<InformationKey name="String" location="XMLTestKey">
- Test String!
-Line2
-</InformationKey>
-```
-
-### vtkInformationIntegerKey
-
-```xml
-<InformationKey name="Integer" location="XMLTestKey">
- 408
-</InformationKey>
-```
-
-### vtkInformationIntegerVectorKey
-
-```xml
-<InformationKey name="IntegerVector" location="XMLTestKey" length="3">
- <Value index="0">
- 1
- </Value>
- <Value index="1">
- 5
- </Value>
- <Value index="2">
- 45
- </Value>
-</InformationKey>
-```
-
-### vtkInformationStringVectorKey
-
-```xml
-<InformationKey name="StringVector" location="XMLTestKey" length="3">
- <Value index="0">
- First
- </Value>
- <Value index="1">
- Second (with whitespace!)
- </Value>
- <Value index="2">
- Third (with
-newline!)
- </Value>
-</InformationKey>
-```
-
-### vtkInformationUnsignedLongKey
-
-```xml
-<InformationKey name="UnsignedLong" location="XMLTestKey">
- 9
-</InformationKey>
-```
diff --git a/Documentation/Doxygen/IOXMLTimeInFieldData.md b/Documentation/Doxygen/IOXMLTimeInFieldData.md
deleted file mode 100644
index e3b79054da1a18bea88d18c82667ecf1676f54c4..0000000000000000000000000000000000000000
--- a/Documentation/Doxygen/IOXMLTimeInFieldData.md
+++ /dev/null
@@ -1,33 +0,0 @@
-Field Data as Time Meta-Data in VTK XML File Formats
-====================================================
-
-As of VTK 8.2, VTK XML readers and writers support embedding time
-meta-data as a field array. This is demonstrated best with an example:
-
-```xml
-<VTKFile type="PolyData" version="1.0" byte_order="LittleEndian" header_type="UInt64">
- <PolyData>
- <FieldData>
- <DataArray type="Float64" Name="TimeValue" NumberOfTuples="1">1.24
- </DataArray>
- </FieldData>
- ...
-</VTKFile>
-```
-
-Here TimeValue is a regular double precision array that has a single value of 1.24.
-The XML readers will treat this array in a special way. When they encounter this array
-during the meta-data stage (`RequestInformation()`), they will read the value from
-this array and generate a `vtkStreamingDemandDrivenPipeline::TIME_STEPS()` key
-in the output information containing this value.
-
-In addition, the XML writers will generate a field array of name TimeValue in the
-output, if they encounter time value in their input (`vtkDataObject::DATA_TIME_STEP()`).
-This is done even if the data does not have a TimeValue array. Furthermore, even such
-an array exists, it will be replaced with one that contains the value from
-`vtkDataObject::DATA_TIME_STEP()` to make sure that the value is consistent with the
-pipeline value.
-
-This change may appear pointless on its own as a single time value is not very useful.
-Its main use is when reading file series as it is done by ParaView's file (time) series
-readers.
diff --git a/Documentation/Doxygen/ModuleMigration.md b/Documentation/Doxygen/ModuleMigration.md
deleted file mode 100644
index 73c7ed07155f0ebcf8088106a7c3e5275537db94..0000000000000000000000000000000000000000
--- a/Documentation/Doxygen/ModuleMigration.md
+++ /dev/null
@@ -1,359 +0,0 @@
-# Module Migration from VTK 8.2 to 9+
-
-VTK 8.2 and older contained a module system which was based on variables and
-informed CMake's migration to target-based properties and interactions. This
-was incompatible with the way VTK ended up doing it. With VTK 9, its module
-system has been reworked to use CMake's targets.
-
-This document may be used as a guide to updating code using old VTK modules into
-code using new VTK modules.
-
-## Using modules
-
-If your project is just using VTK's modules and not declaring any of your own
-modules, porting involves a few changes to the way VTK is found and used.
-
-The old module system made variables available for using VTK.
-
-```cmake
-find_package(VTK
- REQUIRED
- COMPONENTS
- vtkCommonCore
- vtkRenderingOpenGL2)
-include(${VTK_USE_FILE})
-
-add_library(usesvtk ...)
-target_link_libraries(usesvtk ${visibility} ${VTK_LIBRARIES})
-target_include_directories(usesvtk ${visibility} ${VTK_INCLUDE_DIRS})
-
-# Pass any VTK autoinit defines to the target.
-target_compile_definitions(usesvtk PRIVATE ${VTK_DEFINITIONS})
-```
-
-This causes problems if VTK is found multiple times within a source tree with
-different components. The new pattern is:
-
-```cmake
-find_package(VTK
- #9.0 # Compatibility support is not provided if 9.0 is requested.
- REQUIRED
- COMPONENTS
- # Old component names are OK, but deprecated.
- #vtkCommonCore
- #vtkRenderingOpenGL2
- # New names reflect the target names in use.
- CommonCore
- RenderingOpenGL2)
-# No longer needed; warns or errors depending on the version requested when
-# finding VTK.
-#include(${VTK_USE_FILE})
-
-add_library(usesvtk ...)
-# VTK_LIBRARIES is provided for compatibility, but not recommended.
-#target_link_libraries(usesvtk ${visibility} ${VTK_LIBRARIES})
-target_link_libraries(usesvtk ${visibility} VTK::CommonCore VTK::RenderingOpenGL2)
-
-# Rather than defining a single `VTK_DEFINITIONS` for use by all relevant
-# targets, the definitions are made as needed with the exact set needed for the
-# listed modules.
-vtk_module_autoinit(
- TARGETS usesvtk
- #MODULES ${VTK_LIBRARIES} # Again, works, but is not recommended.
- MODULES VTK::CommonCore VTK::RenderingOpenGL2)
-```
-
-## Module declaration
-
-The old module system had CMake code declare modules in `module.cmake` files.
-This allowed logic and other things to happen within them which could cause
-module dependencies to be hard to follow. The new module system now provides
-facilities for disabling modules in certain configurations (using `CONDITION`)
-and for optionally depending on modules (using `OPTIONAL_DEPENDS`).
-
-```cmake
-if (NOT SOME_OPTION)
- set(depends)
- if (SOME_OTHER_OPTION)
- list(APPEND depends vtkSomeDep)
- endif ()
- vtk_module(vtkModuleName
- GROUPS
- # groups the module belongs to
- KIT
- # the kit the module belongs to
- IMPLEMENTS
- # modules containing vtkObjectFactory instances that are implemented here
- DEPENDS
- # public dependencies
- #${depends} # no analogy in the new system
- PRIVATE_DEPENDS
- # private dependencies
- ${depends}
- COMPILE_DEPENDS
- # modules which must be built before this one but which are not actually
- # linked.
- TEST_DEPENDS
- # test dependencies
- TEST_OPTIONAL_DEPENDS
- # optional test dependencies
- ${depends}
- #EXCLUDE_FROM_WRAPPING
- # present for modules which cannot be wrapped
- )
-endif ()
-```
-
-This is now replaced with a declarative file named `vtk.module`. This file is
-not CMake code and is instead parsed as an argument list in CMake (variable
-expansions are also not allowed). The above example would translate into:
-
-```
-MODULE
- vtkModuleName
-CONDITION
- SOME_OPTION
-GROUPS
- # groups the module belongs to
-KIT
- # the kit the module belongs to
-#IMPLEMENTABLE # Implicit in the old build system. Now explicit.
-IMPLEMENTS
- # modules containing vtkObjectFactory instances that are implemented here
-DEPENDS
- # public dependencies
-PRIVATE_DEPENDS
- # private dependencies
-OPTIONAL_DEPENDS
- vtkSomeDep
-ORDER_DEPENDS
- # modules which must be built before this one but which are not actually
- # linked.
-TEST_DEPENDS
- # test dependencies
-TEST_OPTIONAL_DEPENDS
- # optional test dependencies
- vtkSomeDep
-#EXCLUDE_WRAP
- # present for modules which cannot be wrapped
-```
-
-Modules may also now be provided by the current project or by an external
-project found by `find_package` as well.
-
-## Declaring sources
-
-Sources used to be listed just as `.cxx` files. The module system would then
-search for a corresponding `.h` file, then add it to the list. Some source file
-properties could be used to control header-only or private headers.
-
-In this example, we have a module with the following sources:
-
- - `vtkPublicClass.cxx` and `vtkPublicClass.h`: Public VTK class meant to be
- wrapped and its header installed.
- - `vtkPrivateClass.cxx` and `vtkPrivateClass.h`: Private VTK class not meant
- for use outside of the module.
- - `helper.cpp` and `helper.h`: Private API, but not following VTK's naming
- conventions.
- - `public_helper.cpp` and `public_helper.h`: Public API, but not following
- VTK's naming conventions.
- - `vtkImplSource.cxx`: A source file without a header.
- - `public_header.h`: A public header without a source file.
- - `template.tcc` and `template.h`: Public API, but not following VTK's naming
- conventions.
- - `private_template.tcc` and `private_template.h`: Private API, but not
- following VTK's naming conventions.
- - `vtkPublicTemplate.txx` and `vtkPublicTemplate.h`: Public template sources.
- Wrapped and installed.
- - `vtkPrivateTemplate.txx` and `vtkPrivateTemplate.h`: Private template
- sources.
- - `vtkOptional.cxx` and `vtkOptional.h`: Private API which requires an
- optional dependency.
-
-The old module's way of building these sources is:
-
-```cmake
-set(Module_SRCS
- vtkPublicClass.cxx
- vtkPrivateClass.cxx
- helper.cpp
- helper.h
- public_helper.cpp
- public_helper.h
- public_header.h
- vtkImplSource.cxx
- vtkPublicTemplate.txx
- vtkPrivateTemplate.txx
- template.tcc # Not detected as a template, so not installed.
- template.h
- private_template.tcc
- private_template.h
-)
-
-# Mark some files as only being header files.
-set_source_files_properties(
- public_header.h
- HEADER_FILE_ONLY
-)
-
-# Mark some headers as being private.
-set_source_files_properties(
- helper.h
- private_template.h
- public_header.h
- template.h
- vtkImplSource.cxx # no header
- vtkPrivateTemplate.h
- PROPERTIES SKIP_HEADER_INSTALL 1
-)
-
-set(${vtk-module}_HDRS # Magic variable
- public_helper.h
- template.h
- #helper.h # private headers just go ignored.
-)
-
-# Optional dependencies are detected through variables.
-if (Module_vtkSomeDep)
- list(APPEND Module_SRCS
- # Some optional file.
- vtkOptional.cxx)
-endif ()
-
-vtk_module_library(vtkModuleName ${Module_SRCS})
-```
-
-While with the new system, source files are explicitly declared using argument
-parsing.
-
-```cmake
-set(classes
- vtkPublicClass)
-set(private_classes
- vtkPrivateClass)
-set(sources
- helper.cpp
- public_helper.cpp
- vtkImplSource.cxx)
-set(headers
- public_header.h
- public_helper.h
- template.h)
-set(private_headers
- helper.h
- private_template.h)
-
-set(template_classes
- vtkPublicTemplate)
-set(private_template_classes
- vtkPrivateTemplate)
-set(templates
- template.tcc)
-set(private_templates
- private_template.tcc)
-
-# Optional dependencies are detected as targets.
-if (TARGET vtkSomeDep)
- # Optional classes may not be public (though there's no way to actually
- # enforce it, optional dependencies are always treated as private.
- list(APPEND private_classes
- vtkOptional)
-endif ()
-
-vtk_module_add_module(vtkModuleName
- # File pairs which follow VTK's conventions. The headers will be wrapped and
- # installed.
- CLASSES ${classes}
- # File pairs which follow VTK's conventions, but are not for use outside the
- # module.
- PRIVATE_CLASSES ${private_classes}
- # Standalone sources (those without headers or which do not follow VTK's
- # conventions).
- SOURCES ${sources}
- # Standalone headers (those without sources or which do not follow VTK's
- # conventions). These will be installed.
- HEADERS ${public_headers}
- # Standalone headers (those without sources or which do not follow VTK's
- # conventions), but are not for use outside the module.
- PRIVATE_HEADERS ${private_headers}
-
- # Templates are also supported.
-
- # Template file pairs which follow VTK's conventions. Both files will be
- # installed (only the headers will be wrapped).
- TEMPLATE_CLASSES ${template_classes}
- # Template file pairs which follow VTK's conventions, but are not for use
- # outside the module.
- PRIVATE_TEMPLATE_CLASSES ${private_template_classes}
- # Standalone template files (those without headers or which do not follow
- # VTK's conventions). These will be installed.
- TEMPLATES ${templates}
- # Standalone template files (those without headers or which do not follow
- # VTK's conventions), but are not for use outside the module.
- PRIVATE_TEMPLATES ${private_templates}
-)
-```
-
-Note that the arguments with `CLASSES` in their name expand to pairs of files
-with the `.h` and either `.cxx` or `.txx` extension based on whether it is a
-template or not. Projects not using this convention may use the `HEADERS`,
-`SOURCES`, and `TEMPLATES` arguments instead.
-
-## Object Factories
-
-Previously, object factories were made using implicit variable declaration magic
-behind the scenes. This is no longer the case and proper CMake APIs for them are
-available.
-
-```cmake
-set(sources
- vtkObjectFactoryImpl.cxx
- # This path is made by `vtk_object_factory_configure` later.
- "${CMAKE_CURRENT_BINARY_DIR}/${vtk-module}ObjectFactory.cxx")
-
-# Make a list of base classes we will be overriding.
-set(overrides vtkObjectFactoryBase)
-# Make a variable declaring what the override for the class is.
-set(vtk_module_vtkObjectFactoryBase_override "vtkObjectFactoryImpl")
-# Generate a source using the list of base classes overridden.
-vtk_object_factory_configure("${overrides}")
-
-vtk_module_library("${vtk-module}" "${sources}")
-```
-
-This is now handled using proper APIs instead of variable lookups.
-
-```cmake
-set(classes
- vtkObjectFactoryImpl)
-
-# Explicitly declare the override relationship.
-vtk_object_factory_declare(
- BASE vtkObjectFactoryBase
- OVERRIDE vtkObjectFactoryImpl)
-# Collects the set of declared overrides and writes out a source file.
-vtk_object_factory_declare(
- # The path to the source is returned as a variable.
- SOURCE_FILE factory_source
- # As is its header file.
- HEADER_FILE factory_header
- # The export macro is now explicitly passed (instead of assumed based on the
- # current module context).
- EXPORT_MACRO MODULE_EXPORT)
-
-vtk_module_add_module(vtkModuleName
- CLASSES ${classes}
- SOURCES "${factory_source}"
- PRIVATE_HEADERS "${factory_header}")
-```
-
-## Building a group of modules
-
-This was not well supported in the old module system. Basically, it involved
-setting up the source tree like VTK expects and then including the
-`vtkModuleTop` file. This is best just rewritten using the following CMake APIs:
-
- - {cmake:command}`vtk_module_find_modules`
- - {cmake:command}`vtk_module_find_kits`
- - {cmake:command}`vtk_module_scan`
- - {cmake:command}`vtk_module_build`
diff --git a/Documentation/Doxygen/ModuleSystem.md b/Documentation/Doxygen/ModuleSystem.md
deleted file mode 100644
index 858ae88ef49b2ff13af273f081829fd85e993dc3..0000000000000000000000000000000000000000
--- a/Documentation/Doxygen/ModuleSystem.md
+++ /dev/null
@@ -1,1052 +0,0 @@
-# Module System
-
-VTK 9.0 introduces a new build system compared to previous versions. This
-version uses CMake's built-in functionality for behaviors that were performed
-manually in the previous iteration of the build system.
-
-## Terminology
-
- - **module**: A unit of API provided by a project. This is the core of the
- system and there are lots of features available through this mechanism that
- are not provided by CMake's library or other usage requirements.
- - **group**: A configure-time collection of modules. These may be used to
- control whether member modules will be built or not with a single flag.
- - **kit**: A collection of modules for which all the compiled code is placed
- in a single library.
- - **property**: An attribute of a module. Only of real interest to developers
- of the module system and its extensions.
- - **autoinit**: A mechanism for triggering registration to global registries
- based on the complete set of linked-to libraries.
- - **third party**: A module representing an external dependency.
- - **enable status**: A 4-way state to allow for "weak" and "strong" selection
- or deselection of a module or group for building.
-
-## Principles
-
-The module system was designed with a number of principles in mind. These
-should be followed as much as possible when developing extensions as well.
-
- - The minimum CMake version required by the module system should be as low
- as possible to get the required features. For example, if a new feature is
- available in 3.15 that improves core module functionality, that'd be a
- reasonable reason to require it. But a bugfix in 3.10 that can be worked
- around should not bump the minimum version. Currently CMake 3.8 is
- expected to work, though various features (such as kits) are only
- available with newer CMake versions.
- - Build tree looks like the install tree. The layout of the build tree is set
- up to mirror the layout of the install tree. This allows more code content
- to be shared between build and install time.
- - Convention over configuration. CMake conventions should be followed. Of
- note, projects are assumed to be "well-behaved" including, but not limited
- to:
- - use of [`BUILD_SHARED_LIBS`][BUILD_SHARED_LIBS] to control shared vs.
- static library compilation;
- - use of [`GNUInstallDirs`][GNUInstallDirs]; and
- - sensible defaults based on things like
- [`CMAKE_PROJECT_NAME`][cmake-CMAKE_PROJECT_NAME] as set by the
- [`project()`][cmake-project] function.
- - Configuration through API. Where configuration is provided, instead of
- using global state or "magic" variables, configuration should be provided
- through parameters to the API functions provided. Concessions are made for
- rarely-used functionality or where the API would be complicated to plumb
- through the required information. These variables (which are typically
- parameterized) are documented at the end of this document. Such variables
- should be named so that it is unambiguous that they are for the module
- system.
- - Don't pollute the environment. Variables should be cleaned up at the end of
- macros and functions should use variable names that don't conflict with the
- caller environment (usually by prefixing with `_function_name_` or the
- like).
- - Relocatable installs. Install trees should not bake-in paths from the build
- tree or build machine (at least by default). This makes it easier to create
- packages from install trees instead of having to run a post-processing step
- over it before it may be used for distributable packages.
-
-[BUILD_SHARED_LIBS]: https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html
-[GNUInstallDirs]: https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html
-[cmake-CMAKE_PROJECT_NAME]: https://cmake.org/cmake/help/latest/variable/CMAKE_PROJECT_NAME.html
-[cmake-project]: https://cmake.org/cmake/help/latest/command/project.html
-
-## Build process
-
-Building modules involves two phases. The first phase is called "scanning" and
-involves collecting all the information necessary for the second phase,
-"building". Scanning uses the {cmake:command}`vtk_module_scan` function to search the
-{ref}`vtk.module <module-parse-module>` files for metadata, gathers the set of modules
-to build and returns them to the caller. That list of modules is eventually passed to
-{cmake:command}`vtk_module_build` which sorts the modules for their build order and then
-builds each module in turn. This separation allows for scanning and building
-modules in different groups. For example, the main set of modules may be scanned
-to determine which of some internal set of modules are required by those which
-is then scanned separately with different options.
-
-Scanning should occur from the leaf-most module set and work its way inward to
-the lower levels. This is done so that modules in the lower level that are
-required higher up can be enabled gracefully. Builds should start at the lower
-level and move up the tree so that targets required by the higher groups exist
-when they are built.
-
-[vtk_module_scan]: https://vtk.org/doc/nightly/html/group__module.html#ga35849d7807a98a60e99e0a1c8ff54181
-
-## Modules
-
-Modules are described by {ref}`vtk.module <module-parse-module>` files. These files are "scanned" using
-the {cmake:command}`vtk_module_scan` function. They provide all the information necessary for
-the module system to:
-
- - provide cache variables for selecting the module (e.g.,
- `VTK_MODULE_ENABLE_ModuleName`);
- - construct the dependency tree to automatically enable or disable modules
- based on whether it is built or not;
- - provide module-level metadata (such as exclusion from any wrapping and
- marking modules as third party)
-
-The {ref}`vtk.module <module-parse-module>` files are read and "parsed", but not executed directly. This
-ensures that the module files do not contain any procedural CMake code. The
-files may contain comments starting with `#` like CMake code. They may either
-be passed manually to {cmake:command}`vtk_module_scan` or discovered by using the
-{cmake:command}`vtk_module_find_modules` convenience function.
-
-The most important (and only required) parameter is the `NAME` of a module.
-This is used as the target name in CMake and is how the module's target should
-be referred to in all CMake code, inside the build and from the
-[`find_package`][cmake-find_package] which provides the module. To change the
-name of the compiled artifact (library or executable), the `LIBRARY_NAME`
-argument may be used.
-
-It is highly recommended to provide a `DESCRIPTION` for the module. This is
-added to the documentation for the cache variable so that the user has more than
-just the module name to know what the module's purpose is.
-
-Modules may also belong to groups which are created implicitly by adding
-modules to the same-named group. Groups are listed under the `GROUPS` argument
-and are checked in order for a non-default setting to use.
-
-A module may be hidden by using the `CONDITION` argument. The values passed to
-this field is added into a CMake `if` statement and checked for validity (all
-quoting is passed along verbatim). If the condition evaluates to `FALSE`, the
-module is treated as if it did not exist at all.
-
-[cmake-find_package]: https://cmake.org/cmake/help/latest/command/find_package.html
-
-### Module metadata
-
-A number of pieces of metadata are considered important enough to indicate them
-at the module level. These are used for managing slightly different workflows
-for modules which have these properties.
-
- - `EXCLUDE_WRAP`: This marks the module with a flag that all language wrapping
- facilities should use to know that this module is not meant for wrapping in
- any language. Usually this is for modules containing user interface classes,
- low-level functionality, or logic that is language specific.
- - `IMPLEMENTABLE` and `IMPLEMENTS`: These are used by the
- [autoinit](#autoinit) functionality to trigger the static factory
- registration calls. A module which is listed under an `IMPLEMENTS` list must
- be marked as `IMPLEMENTABLE` itself.
- - `THIRD_PARTY`: Indicates that the module represents a third party
- dependency. It may be internal or external to the source tree, but may be
- used as an additional configuration point if necessary. These modules are
- implicitly `EXCLUDE_WRAP`, not `IMPLEMENTABLE` and do not `IMPLEMENTS` any
- module.
-
-### Enabling modules for build
-
-Modules are enabled in a number of ways. These ways allow for project control
-and user control of which modules should be built or not. There are 4 states for
-controlling a module's {ref}`enable status <module-enable-status>`
-as well as a `DEFAULT`
-setting which is used to allow for other mechanisms to select the enable status:
-
- - `YES`: The module must be built.
- - `NO`: The module must not be built. If a `YES` module has a `NO` module in
- its dependency tree, an error is raised.
- - `WANT`: The module should be built. It will not be built, however, if it
- depends on a `NO` module.
- - `DONT_WANT`: The module doesn't need to be built. It will be built if a
- `YES` or `WANT` module depends on it.
- - `DEFAULT`: Look at other metadata to determine the status.
-
-The first check for modules are via the `REQUEST_MODULES` and `REJECT_MODULES`
-arguments to the `vtk_module_scan` function. Modules passed to
-`REQUEST_MODULES` are treated as if they use `YES` and `REJECT_MODULES` as if
-they use `NO`. A module may not be passed to both arguments. Modules selected
-in this way do not have CMake cache variables exposed for them (since it is
-assumed they are selected via some other mechanism outside the module system).
-
-The next selector is the `VTK_MODULE_ENABLE_` variable for the module. This is
-added to the cache and defaults to `DEFAULT`. Assuming `HIDE_MODULES_FROM_CACHE`
-is not set to `ON`, this setting is exposed in the cache and allows users to
-change the status of modules not handled via the `REQUEST_MODULES` and
-`REJECT_MODULES` mechanism.
-
-If a module is still selected as `DEFAULT`, the list of `GROUPS` it is a member
-of is used. In order, each group is looked at for a non-`DEFAULT` value. If so,
-its value is used for the module. Groups also default to using `DEFAULT` for
-their setting, but a project may set the `_vtk_module_group_default_${group}`
-variable to change this default value.
-
-After all of the above logic, if a module is still marked as `DEFAULT`, the
-`WANT_BY_DEFAULT` argument to {cmake:command}`vtk_module_scan` is used to determine whether
-it is treated as a `WANT` or `DONT_WANT` request.
-
-Now that all modules have a non-`DEFAULT` enable setting, the set of modules and
-kits that are available may be determined by traversing the dependency tree of
-the modules.
-
-### Dependencies
-
-Modules have three types of dependencies:
-
- - `DEPENDS`: These are dependencies which must be available and are
- transitively provided to modules depending on this module. The API of the
- module may be affected by changes in these modules. This includes, but is
- not limited to, classes in this module inherit or expose classes from the
- dependent modules.
- - `PRIVATE_DEPENDS`: Dependencies which are only used in the implementation
- details of the module. The API of the module is not affected by changes in
- these modules.
- - `OPTIONAL_DEPENDS`: Dependencies which will be used if available, but the
- implementation can cope with their absence. These are always treated as
- `PRIVATE_DEPENDS` if they are available.
-
-Modules which are listed in `DEPENDS` or `PRIVATE_DEPENDS` are always available
-to the module and can be assumed to exist if the module is being built. Modules
-listed in `OPTIONAL_DEPENDS` cannot be assumed to exist. In CMake code, a
-`TARGET optional_depend` condition may be used to detect whether it is available
-or not. The module system will add a `VTK_MODULE_ENABLE_${module}` compilation
-definition set to either `0` or `1` if it is available for use in the module's
-code. This flag is made preprocessor-safe by replacing any `::` in the module
-name with `_`. So an optional dependency on `Namespace::Target` will use a flag
-named `VTK_MODULE_ENABLE_Namespace_Target`.
-
-At this stage, the dependency tree for all scanned modules is traversed, marking
-dependencies of `YES` modules as those that should be built, marking modules
-depending on `NO` modules as not to be built (and triggering an error if a
-conflict is found). Any `WANT` modules that have not been found in the trees of
-`YES` or `NO` modules are then enabled with their dependencies.
-
-There is a script to help figuring out dependencies when building your own modules
-or VTK-dependant code (*.cxx, *.h) in order to generate a [`find_package`][cmake-find_package]
-command. The required json argument is only available in a build tree though.
-
-`Utilities/Maintenance/FindNeededModules.py -s /path/to/sources -j path/to/vtk_build/modules.json`
-
-### Testing
-
-There is some support for testing in the module system, but it is not as
-comprehensive as the build side. This is because testing infrastructure and
-strategies vary wildly between projects. Rather than trying to handle the
-minimum baseline of any plausible testing infrastructure or framework, the
-module system merely handles dependency management for testing and entering a
-subdirectory with the tests.
-
-Modules may have `TEST_DEPENDS` and `TEST_OPTIONAL_DEPENDS` lists provided as
-well. These modules are required or optionally used by the testing code for the
-module.
-
-When scanning, the `ENABLE_TESTS` argument may be set to `ON`, `OFF`, `WANT`
-(the default), or `DEFAULT`. Modules which appear in `TEST_DEPENDS` for the
-module are affected by this setting.
-
- - `ON`: Modules required for testing are treated as required. Tests will be
- enabled.
- - `OFF`: Tests will not be enabled.
- - `WANT`: If possible, `TEST_DEPENDS` modules will also be enabled if they are
- not disabled in some other way.
- - `DEFAULT`: Check when tests are checked whether all of `TEST_DEPENDS` are
- available. If they are, enable testing for the module, otherwise skip it.
-
-The only guarantee for testing provided is that all modules in the
-`TEST_DEPENDS` will be available before the testing is added and
-`TEST_OPTIONAL_DEPENDS` are available if they'd be available at all (i.e., they
-won't be made available later).
-
-Modules may also have `TEST_LABELS` set to ease labeling all tests for the
-module. The module system itself does nothing with this other than set a global
-property with the value. It is up to any test infrastructure used within the
-module's CMake code to make use of the value.
-
-The tests for a module are expected to live in a subdirectory of the module code
-itself. The name of this directory is given by the `TEST_DIRECTORY_NAME`
-argument to the {cmake:command}`vtk_module_build` function. If the directory is available and
-the module's testing is enabled, the module system will
-[`add_subdirectory`][cmake-add_subdirectory] this directory at the appropriate
-time. This is decoupled so that testing code can depend on modules that depend
-on the module that is being tested and the same `TARGET ${dependency}` check can
-be used for optional module dependencies.
-
-[cmake-add_subdirectory]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html
-
-## Building modules
-
-After scanning is complete, {cmake:command}`vtk_module_scan` returns a list of modules and
-kits to build in the variables given by the `PROVIDES_MODULES` and
-`PROVIDES_KITS` arguments to it. It also provides lists of modules that were
-found during scanning that were not scanned by that call. These are given back
-in the variables passed to the `UNRECOGNIZED_MODULES` and `REQUIRES_MODULES`
-variables.
-
-The `UNRECOGNIZED_MODULES` list contains modules passed to `REQUIRES_MODULES`
-and `REJECT_MODULES` that were not found during the scan. This typically
-indicates that the values passed to those arguments were not constructed
-properly. However, it may also mean that they should be passed on to further
-scans if they may be found elsewhere. Callers should handle the variable as
-necessary for their use case.
-
-The `REQUIRES_MODULES` are modules that were named as dependencies of the
-scanned modules and need to be provided in some way before building the provided
-modules (the build step will require that they exist when it tries to build the
-modules which required them). These can be passed on to future
-`REQUIRES_MODULES` arguments in future scans or used to error out depending on
-the use case of the caller.
-
-When using {cmake:command}`vtk_module_build`, the `PROVIDES_MODULES` and `PROVIDES_KITS` from
-a single scan should be passed together. Multiple scans may be built together as
-well if they all use the same build parameters as each other.
-
-### Build-time parameters
-
-The {cmake:command}`vtk_module_build` function is where the decision to build with or without
-kits is decided through the `BUILD_WITH_KITS` option. Only if this is set will
-kits be built for this set of modules.
-
-The decision to default third party modules to using an external or internal
-copy (where such a decision is possible) is done using the `USE_EXTERNAL`
-argument.
-
-Where build artifacts end up in the build tree are left to CMake's typical
-variables for controlling these locations:
-
- - [`CMAKE_ARCHIVE_OUTPUT_DIRECTORY`][cmake-CMAKE_ARCHIVE_OUTPUT_DIRECTORY]
- - [`CMAKE_LIBRARY_OUTPUT_DIRECTORY`][cmake-CMAKE_LIBRARY_OUTPUT_DIRECTORY]
- - [`CMAKE_RUNTIME_OUTPUT_DIRECTORY`][cmake-CMAKE_RUNTIME_OUTPUT_DIRECTORY]
-
-The defaults for these place outputs into the binary directory where the targets
-were added. The module system will set these to be sensible for itself if they
-are not already set, but it is recommended to set these at the top-level so that
-targets not built under {cmake:command}`vtk_module_build` also end up at a sensible location.
-
-[cmake-CMAKE_ARCHIVE_OUTPUT_DIRECTORY]: https://cmake.org/cmake/help/latest/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.html
-[cmake-CMAKE_LIBRARY_OUTPUT_DIRECTORY]: https://cmake.org/cmake/help/latest/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.html
-[cmake-CMAKE_RUNTIME_OUTPUT_DIRECTORY]: https://cmake.org/cmake/help/latest/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.html
-
-### Library parameters
-
-When building libraries, it is sometimes useful to have top-level control of
-library metadata. For example, VTK suffixes its library filenames with a version
-number. The variables that control this include:
-
- - `LIBRARY_NAME_SUFFIX`: If non-empty, all libraries and executable names will
- be suffixed with this value prefixed with a hyphen (e.g., a suffix of `foo`
- will make `Namespace::Target`'s library be named `Target-foo` or, if the
- module sets its `LIBRARY_NAME` to `nsTarget`, `nsTarget-foo`).
- - `VERSION`: Controls the [`VERSION`][cmake-VERSION] property for all library
- modules.
- - `SOVERSION`: Controls the [`SOVERSION`][cmake-SOVERSION] property for all
- library modules.
-
-[cmake-VERSION]: https://cmake.org/cmake/help/latest/prop_tgt/VERSION.html
-[cmake-SOVERSION]: https://cmake.org/cmake/help/latest/prop_tgt/SOVERSION.html
-
-### Installation support
-
-{cmake:command}`vtk_module_build` also offers arguments to aid in installing module
-artifacts. These include destinations for pieces that are installed, CMake
-packaging controls, and components to use for the installations.
-
-A number of destinations control arguments are provided:
-
- - `ARCHIVE_DESTINATION`
- - `HEADERS_DESTINATION`
- - `LIBRARY_DESTINATION`
- - `RUNTIME_DESTINATION`
- - `CMAKE_DESTINATION`
- - `LICENSE_DESTINATION`
- - `HIERARCHY_DESTINATION`
-
-See the API documentation for default values for each which are based on
-[`GNUInstallDirs`][GNUInstallDirs] variables. Note that all installation
-destinations are expected to be relative paths. This is because the conveniences
-provided by the module system are all assumed to be installed to a single prefix
-([`CMAKE_INSTALL_PREFIX`][cmake-CMAKE_INSTALL_PREFIX]) and placed underneath it.
-
-Suppression of header installation is provided via the `INSTALL_HEADERS`
-argument to {cmake:command}`vtk_module_build`. Setting this to `OFF` will suppress the
-installation of:
-
- - headers
- - CMake package files
- - hierarchy files (since their use requires headers)
-
-Basically, suppression of headers means that SDK components for the built
-modules are not available in the install tree.
-
-Components for the installation are provided via the `HEADERS_COMPONENT` and
-`TARGETS_COMPONENT` arguments. The former is used for SDK bits and the latter
-for runtime bits (libraries, executables, etc.).
-
-For CMake package installation, the `PACKAGE` and `INSTALL_EXPORT` arguments are
-available. The former controls the names used by the CMake files created by the
-module system while the former is the export set to use for the member modules
-when creating those CMake files. Non-module targets may also exist in this
-export set when {cmake:command}`vtk_module_build` is called, but the export set is considered
-"closed" afterwards since it has already been exported (if `INSTALL_HEADERS` is
-true).
-
-[cmake-CMAKE_INSTALL_PREFIX]: https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html
-
-### Test data information
-
-The directory that is looked for in each module is specified by using the
-`TEST_DIRECTORY_NAME` argument. If it is set to the value of `NONE`, no testing
-directories will be searched for. It defaults to `Testing` due to VTK's
-conventions.
-
-The module system, due to VTK's usage of it, has convenience parameters for
-controlling the [`ExternalData`][ExternalData] module that is available to
-testing infrastructure. These include:
-
- - `TEST_DATA_TARGET`: The data target to use for tests.
- - `TEST_INPUT_DATA_DIRECTORY`: Where `ExternalData` should look for data
- files.
- - `TEST_OUTPUT_DATA_DIRECTORY`: Where `ExternalData` should place the
- downloaded data files.
- - `TEST_OUTPUT_DIRECTORY`: Where tests should place output files.
-
-Each is provided in the testing subdirectory as `_vtk_build_${name}`, so the
-`TEST_DATA_TARGET` argument is available as `_vtk_build_TEST_DATA_TARGET`.
-
-[ExternalData]: https://cmake.org/cmake/help/latest/module/ExternalData.html
-
-## Building a module
-
-Building a module is basically the same as a normal CMake library or executable,
-but is wrapped to use arguments to facilitate wrapping, exporting, and
-installation of the tools as well.
-
-There are two main functions provided for this:
-
- - {cmake:command}`vtk_module_add_module`
- - {cmake:command}`vtk_module_add_executable`
-
-The former creates a library for the module being built while the latter can
-create an executable for the module itself or create utility executable
-associated with the module. The module system requires that the `CMakeLists.txt`
-for a module create a target with the name of the module. In the case of
-`INTERFACE` modules, it suffices to create the module manually in many cases.
-
-### Libraries
-
-Most modules end up being libraries that can be linked against by other
-libraries. Due to cross-platform support generally being a good thing, the
-`EXPORT_MACRO_PREFIX` argument is provided to specify the prefix for macro names
-to be used by [`GenerateExportHeader`][GenerateExportHeader]. By default, the
-`LIBRARY_NAME` for the module is transformed to uppercase to make the prefix.
-
-Some modules may need to add additional information to the library name that
-will be used that is not statically know and depends on other environmental
-settings. The `LIBRARY_NAME_SUFFIX` may be specified to add an additional suffix
-to the `LIBRARY_NAME` for the module. The {cmake:command}`vtk_module_build`
-`LIBRARY_NAME_SUFFIX` argument value will be appended to this name as well.
-
-Normally, libraries are built according to the
-[`BUILD_SHARED_LIBS`][BUILD_SHARED_LIBS] variable, however, some modules may
-need to be built statically all the time. The `FORCE_STATIC` parameter exists
-for this purpose. This is generally only necessary if the module is in some
-other must-be-static library's dependency tree (which may happen for a number of
-reasons). It is not an escape hatch for general usage; it is there because use
-cases which only support static libraries (even in a shared build) exist.
-
-If a library module is part of a kit and it is being built via the
-{cmake:command}`vtk_module_build` `BUILD_WITH_KITS` argument, it will be built as an
-[`OBJECT`][cmake-OBJECT] library and the kit machinery in {cmake:command}`vtk_module_build`
-will create the resulting kit library artifact.
-
-Header-only modules must pass `HEADER_ONLY` to create an `INTERFACE` library
-instead of expecting a linkable artifact.
-
-```{note}
-`HEADER_ONLY` modules which are part of kits is currently untested. This
-should be supported, but might not work at the moment.
-```
-
-[cmake-OBJECT]: https://cmake.org/cmake/help/latest/command/add_library.html
-[GenerateExportHeader]: https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html
-
-#### Source listing
-
-Instead of using CMake's "all sources in a single list" pattern for
-`add_library`, {cmake:command}`vtk_module_add_module` classifies its source files explicitly:
-
- - `SOURCES`
- - `HEADERS`
- - `TEMPLATES`
-
-The `HEADERS` and `TEMPLATES` are installed into the `HEADERS_DESTINATION`
-specified to {cmake:command}`vtk_module_build` and may be added to a subdirectory of this
-destination by using the `HEADERS_SUBDIR` argument. Note that the structure of
-the header paths passed is ignored. If more structure is required from the
-installed header layout, {cmake:command}`vtk_module_install_headers` should be used.
-
-Files passed via `HEADERS` are treated as the API interface to the code of the
-module and are added to properties so that [language wrappers](#wrapping) can
-discover the API of the module.
-
-```{note}
-Only headers passed via `HEADERS` are eligible for wrapping; those
-installed via {cmake:command}`vtk_module_install_headers` are not. This is a known limitation
-at the moment.
-```
-
-There are also private variations for `HEADERS` and `TEMPLATES` named
-`PRIVATE_HEADERS` and `PRIVATE_TEMPLATES` respectively. These are never
-installed nor exposed to wrapping mechanisms.
-
-There are also a couple of convenience parameters that use VTK's file naming
-conventions to ease usage. These include:
-
- - `CLASSES`: For each value `<class>`, adds `<class>.cxx` to `SOURCES` and
- `<class>.h` to `HEADERS`.
- - `TEMPLATE_CLASSES`: For each value `<class>`, adds `<class>.txx` to
- `TEMPLATES` and `<class>.h` to `HEADERS`.
- - `PRIVATE_CLASSES`: For each value `<class>`, adds `<class>.cxx` to `SOURCES`
- and `<class>.h` to `PRIVATE_HEADERS`.
- - `PRIVATE_TEMPLATE_CLASSES`: For each value `<class>`, adds `<class>.txx` to
- `PRIVATE_TEMPLATES` and `<class>.h` to `PRIVATE_HEADERS`.
-
-### Executables
-
-Executables may be created using {cmake:command}`vtk_module_add_executable`. The first
-argument is the name of the executable to build. Since the scanning phase does
-not know what kind of target will be created for each module (and it may change
-based on other configuration values), an executable module which claims it is
-part of a kit raises an error since this is not possible to do.
-
-For modules that are executables using this function, the metadata from the
-module information is used to set the relevant properties. The module
-dependencies are also automatically linked in the same way as a library module
-would do so.
-
-For utility executables, `NO_INSTALL` may be passed to keep it within the build
-tree. It will not be available to consumers of the project. If the name of the
-executable is different from the target name, `BASENAME` may be used to change
-the executable's name.
-
-### Module APIs
-
-All of CMake's `target_` function calls have {ref}`analogues <module-target-functions>` for
-modules. This is primarily due to the kits feature which causes the target name
-created by the module system that is required to use the `target_` functions
-dependent on whether the module is a member of a kit and kits are being built.
-The CMake version of the function and the module API analogue (as well as
-differences, if any) is:
-
- - [set_target_properties][cmake-set_target_properties] becomes
- {cmake:command}`vtk_module_set_properties`
- - [set_property(TARGET)][cmake-set_property] becomes
- {cmake:command}`vtk_module_set_property`
- - [get_property(TARGET)][cmake-get_property] becomes
- {cmake:command}`vtk_module_get_property`
- - [add_dependencies][cmake-add_dependencies] becomes {cmake:command}`vtk_module_depend`
- - [target_include_directories][cmake-target_include_directories] becomes
- {cmake:command}`vtk_module_include`
- - [target_compile_definitions][cmake-target_compile_definitions] becomes
- {cmake:command}`vtk_module_definitions`
- - [target_compile_options][cmake-target_compile_options] becomes
- {cmake:command}`vtk_module_compile_options`
- - [target_compile_features][cmake-target_compile_features] becomes
- {cmake:command}`vtk_module_compile_features`
- - [target_link_libraries][cmake-target_link_libraries] becomes
- {cmake:command}`vtk_module_link`: When kits are enabled, any `PRIVATE` links are
- forwarded to the kit itself. This necessitates making all of these targets
- globally scoped rather than locally scoped.
- - [target_link_options][cmake-target_link_options] becomes
- {cmake:command}`vtk_module_link_options`
-
-[cmake-set_target_properties]: https://cmake.org/cmake/help/latest/command/set_target_properties.html
-[cmake-set_property]: https://cmake.org/cmake/help/latest/command/set_property.html
-[cmake-get_property]: https://cmake.org/cmake/help/latest/command/get_property.html
-[cmake-add_dependencies]: https://cmake.org/cmake/help/latest/command/add_dependencies.html
-[cmake-target_include_directories]: https://cmake.org/cmake/help/latest/command/target_include_directories.html
-[cmake-target_compile_definitions]: https://cmake.org/cmake/help/latest/command/target_compile_definitions.html
-[cmake-target_compile_options]: https://cmake.org/cmake/help/latest/command/target_compile_options.html
-[cmake-target_compile_features]: https://cmake.org/cmake/help/latest/command/target_compile_features.html
-[cmake-target_link_libraries]: https://cmake.org/cmake/help/latest/command/target_link_libraries.html
-[cmake-target_link_options]: https://cmake.org/cmake/help/latest/command/target_link_options.html
-
-## Packaging support
-
-Getting installed packages to work for CMake is, unfortunately, not trivial. The
-module system provides some support for helping with this, but it does place
-some extra constraints on the project so that some assumptions that vastly
-simplify the process can be made.
-
-### Assumptions
-
-The main assumption is that all modules passed to a single {cmake:command}`vtk_module_build`
-have the same CMake namespace (the part up to and including the `::`, if any,
-in a module name. For exporting dependencies, that namespace matches the
-`PACKAGE` argument for {cmake:command}`vtk_module_build`. These are done so that the
-generated code can use
-[`CMAKE_FIND_PACKAGE_NAME`][cmake-CMAKE_FIND_PACKAGE_NAME] variable can be
-used to discover information about the package that is being found.
-
-The package support also assumes that all modules may be queried using
-`COMPONENTS` and `OPTIONAL_COMPONENTS` and that the component name for a module
-corresponds to the name of a module without the namespace.
-
-These rules basically mean that a module named `Namespace::Target` will be found
-using `find_package(Namespace)`, that `COMPONENTS Target` may be passed to
-ensure that that module exists, and `OPTIONAL_COMPONENTS Target` may be passed
-to allow the component to not exist while not failing the main
-[`find_package`][cmake-find_package] call.
-
-[cmake-CMAKE_FIND_PACKAGE_NAME]: https://cmake.org/cmake/help/latest/variable/CMAKE_FIND_PACKAGE_NAME.html
-
-### Creating a full package
-
-The module system provides no support for the top-level file that is used by
-[`find_package`][cmake-find_package]. This is because this logic is highly
-project-specific and hard to generalize in a useful way. Instead, files are
-generated which should be included from the main file.
-
-Here, the list of files generated are based on the `PACKAGE` argument passed to
-{cmake:command}`vtk_module_build`:
-
- - `<PACKAGE>-targets.cmake`: The CMake-generated export file for the targets
- in the `INSTALL_EXPORT`.
- - `<PACKAGE>-vtk-module-properties.cmake`: Properties for the targets exported
- into the build.
-
-The module properties file must be included after the targets file so that they
-exist when it tries to add properties to the imported targets.
-
-### External dependencies
-
-Since the module system is heavily skewed towards using imported targets, these
-targets show up by name in the [`find_package`][cmake-find_package] of the
-project as well. This means that these external projects need to be found to
-recreate their imported targets at that time. To this end, there is the
-{cmake:command}`vtk_module_export_find_packages` function. This function writes a file named
-according to its `FILE_NAME` argument and place it in the build and install
-trees according to its `CMAKE_DESTINATION` argument.
-
-This file will be populated with logic to determine whether third party packages
-found using {cmake:command}`vtk_module_find_package` are required during the
-[`find_package`][cmake-find_package] of the package or not. It will forward
-`REQUIRED` and `QUIET` parameters to other [`find_package`][cmake-find_package]
-calls as necessary based on the `REQUIRED` and `QUIET` flags for the package
-and whether that call is involved in a non-optional `COMPONENT` (a
-component-less [`find_package`][cmake-find_package] call is assumed to mean
-"all components").
-
-This file should be included after the `<PACKAGE>-vtk-module-properties.cmake`
-file generated by the {cmake:command}`vtk_module_build` call so that it can use the module
-dependency information set via that file.
-
-After this file is included, for each component that it checks, it will set
-`${CMAKE_FIND_PACKAGE_NAME}_<component>_FOUND` to 0 if it is not valid and
-append a reason to `${CMAKE_FIND_PACKAGE_NAME}_<component>_NOT_FOUND_MESSAGE`
-so that the package can collate the reason why things are not available.
-
-### Setting the `_FOUND` variable
-
-The module system does not currently help in determining the top-level
-`${CMAKE_FIND_PACKAGE_NAME}_FOUND` variable based on the results of the
-components that were requested and the status of dependent packages. This may be
-provided at some point, but there has not currently been enough experience to
-determine what patterns are available for factoring it out as a utility
-function.
-
-The general pattern should be to go through the list of components requested,
-determine whether targets for those components exist. Then for each found
-component, use the module dependency information to ensure that all targets in
-the dependency trees are found (propagating not-found statuses through the
-dependency tree). The `${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE` should be
-built up based on the reasons the [`find_package`][cmake-find_package] call did
-not work based on these discoveries.
-
-This is the process for modules in a package, but packages may contain
-non-module components, and it is hard for the module system to provide support
-for them, so they are not attempted. See the CMake documentation for more
-details about [creating a package configuration][cmake-create-package-config].
-
-[cmake-create-package-config]: https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html#creating-a-package-configuration-file
-
-## Advanced topics
-
-There are a number of advanced features provided by the module system that are
-not normally required in a simple project.
-
-### Kits
-
-Kits are described in {ref}`vtk.kit <module-parse-kit>` files which act much like {ref}`vtk.module <module-parse-module>`
-files. However, they only have `NAME`, `LIBRARY_NAME`, and `DESCRIPTION` fields.
-These all act just like they do in the `vtk.module` context. These files may
-either be passed manually to {cmake:command}`vtk_module_scan` or discovered by using the
-{cmake:command}`vtk_module_find_kits` convenience function.
-
-Before a module may be a member of a kit, a {ref}`vtk.kit <module-parse-kit>` must declare it and be
-scanned at the same time. This means that kits may only contain modules that are
-scanned with them and cannot be extended later nor may kits be made of modules
-that they do not know about.
-
-#### Requirements
-
-In order to actually use kits, CMake 3.12 is necessary in order to do the
-[`OBJECT`][cmake-OBJECT] library manipulations done behind the scenes to make it
-Just Work. 3.8 is still the minimum version for using a project that is built
-with kits however. This is only checked when kits are actually in use, so
-projects requiring older CMake versions as their minimum version may still
-provide kits so that users with newer CMake versions can use them.
-
-Kits create a single library on disk, but the usage requirements of the modules
-should still be the same (except for that which is inherently required to be
-different by combining libraries). So include directories, compile definitions,
-and other usage requirements should not leak from other modules that are members
-of the same kit.
-
-<a name="autoinit"></a>
-### Autoinit
-
-The module system supports a mechanism for triggering static code construction
-for modules which require it. This cannot be done through normal CMake usage
-requirements because the requirements are intersectional. For example, a module
-`F` having a factory where module `I` provides an implementation for it means
-that a target linking to both `F` and `I` needs to ensure that `I` registers its
-implementation to the factory code. There is no such support in CMake and due to
-the complexities and code generation involved with this support, it is unlikely
-to exist.
-
-Code which uses modules may call the {cmake:command}`vtk_module_autoinit` function to use
-this functionality. The list of modules passed to the function are used to
-compute the defines necessary to trigger the registration to factories when
-necessary.
-
-For details on the implementation of the autoinit system, please see
-{ref}`the relevant section <module-autoinit>` in the API documentation.
-
-<a name="wrapping"></a>
-### Wrapping
-
-VTK comes with support for wrapping its classes into other languages.
-Currently, VTK supports wrapping its classes for use in the Python and Java
-languages. In order to wrap a set of modules for a language, a separate
-function is used for each language.
-
-All languages read the headers of classes with a `__VTK_WRAP__` preprocessor
-definition defined. This may be used to hide methods or other details from the
-wrapping code if wanted.
-
-#### Python
-
-For Python, the {cmake:command}`vtk_module_wrap_python` function must be used. This function
-takes a list of modules in its `MODULES` argument and creates Python modules
-for use under the `PYTHON_PACKAGE` package. No `__init__.py` for this package
-is created automatically and must be provided in some other way.
-
-A target named by the `TARGET` argument is created and installed. This target
-may be linked to in order to be able to import static Python modules. In this
-case, a header and function named according to the basename of `TARGET` (e.g.,
-`VTK::PythonWrapped` has a basename of `PythonWrapped`) must be used. The
-header is named `<TARGET_BASENAME>.h` and the function which adds the wrapped
-modules to the static import table is `<void TARGET_BASENAME>_load()`. This
-function is also created in shared builds, but does nothing so that it may
-always be called in static or shared builds.
-
-The modules will be installed under the `MODULE_DESTINATION` given to the
-function into the `PYTHON_PACKAGE` directory needed for it. The
-{cmake:command}`vtk_module_python_default_destination` function is used to determine a
-default if one is not passed.
-
-The Python wrappers define a `__VTK_WRAP_PYTHON__` preprocessor definition when
-reading code which may be used to hide methods or other details from the Python
-wrapping code.
-
-#### Java
-
-For Java, the {cmake:command}`vtk_module_wrap_java` function must be used. This function
-creates Java sources for classes in the modules passed in its `MODULES`
-argument. The sources are written to a `JAVA_OUTPUT` directory. These then can
-be compiled by CMake normally.
-
-For this purpose, there are `<MODULE>Java` targets which contain a
-`_vtk_module_java_files` properties containing a list of `.java` sources
-generated for the given module. There is also a `<MODULE>Java-java-sources`
-target which may be depended upon if just the source generation needs to used
-in an [`add_dependencies`][cmake-add_dependencies] call.
-
-The Java wrappers define a `__VTK_WRAP_JAVA__` preprocessor definition when
-reading code which may be used to hide methods or other details from the Java
-wrapping code.
-
-#### Hierarchy files
-
-Hierarchy files are used by the language wrapper tools to know the class
-inheritance for classes within a module. Each module has a hierarchy file
-associated with it. The path to a module's hierarchy file is stored in its
-`hierarchy` module property.
-
-### Third party
-
-The module system has support for representing third party modules in its
-build. These may be built as part of the project or represented using other
-mechanisms (usually [`find_package`][cmake-find_package] and a set of imported
-targets from it).
-
-The primary API is {cmake:command}`vtk_module_third_party` which creates a
-`VTK_MODULE_USE_EXTERNAL_Namespace_Target` option for the module to switch
-between an internal and external source for the third party code. This value
-defaults to the setting of the `USE_EXTERNAL` argument for the calling
-{cmake:command}`vtk_module_build` function. Arguments passed under the `INTERNAL` and
-`EXTERNAL` arguments to this command are then passed on to
-{cmake:command}`vtk_module_third_party_internal` or {cmake:command}`vtk_module_third_party_external`,
-respectively, depending on the `VTK_MODULE_USE_EXTERNAL_Namespace_Target`
-option.
-
-Note that third party modules (marked as such by adding the `THIRD_PARTY`
-keyword to a `vtk.module` file) may not be part of a kit, be wrapped, or
-participate in autoinit.
-
-#### External third party modules
-
-External modules are found using CMake's [`find_package`][cmake-find_package]
-mechanism. In addition to the arguments supported by
-{cmake:command}`vtk_module_find_package` (except `PRIVATE`), information about the found
-package is used to construct a module target which represents the third party
-package. The preferred mechanism is to give a list of imported targets to the
-`LIBRARIES` argument. These will be added to the `INTERFACE` of the module and
-provide the third party package for use within the module system.
-
-If imported targets are not available (they really should be created if not),
-variable names may be passed to `INCLUDE_DIRS`, `LIBRARIES`, and `DEFINITIONS`
-to create the module interface.
-
-In addition, any variables which should be forwarded from the package to the
-rest of the build may be specified using the `USE_VARIABLES` argument.
-
-The `STANDARD_INCLUDE_DIRS` argument creates an include interface for the
-module target which includes the "standard" module include directories to.
-Basically, the source and binary directories of the module.
-
-#### Internal third party modules
-
-Internal modules are those that may be built as part of the build. These should
-ideally specify a set of `LICENSE_FILES` indicating the license status of the
-third party code. These files will be installed along with the third party
-package to aid in any licensing requirements of the code. It is also
-recommended to set the `VERSION` argument so that it is known what version of
-the code is provided at a glance.
-
-By default, the `LIBRARY_NAME` of the module is used as the name of the
-subdirectory to include, but this may be changed by using the `SUBDIRECTORY`
-argument.
-
-Header-only third party modules may be indicated by using the `HEADER_ONLY`
-argument. Modules which represent multiple libraries at once from a project may
-use the `INTERFACE` argument.
-
-The `STANDARD_INCLUDE_DIRS` argument creates an include interface for the
-module target which includes the "standard" module include directories to.
-Basically, the source and binary directories of the module. A subdirectory may
-be used by setting the `HEADERS_SUBDIR` option. It is implied for
-`HEADERS_ONLY` third party modules.
-
-After the subdirectory is added a target with the module's name must exist.
-However, a target is automatically created if it is `HEADERS_ONLY`.
-
-##### Properly shipping internal third party code
-
-There are many things that really should be done to ship internal third party
-code (also known as vendoring) properly. The issue is mainly that the internal
-code may conflict with other code bringing in another copy of the same package
-into a process. Most platforms do not behave well in this situation.
-
-In order to avoid conflicts at every level possible, a process called "name
-mangling" should be performed. A non-exhaustive list of name manglings that
-must be done to fully handle this case includes:
-
- - moving headers to a subdirectory (to avoid compilations from finding
- incompatible headers);
- - changing the library name (to avoid DLL lookups from finding incompatible
- copies); and
- - mangling symbols (to avoid symbol lookup from confusing two copies in the
- same process).
-
-Some projects may need further work like editing CMake APIs or the like to be
-mangled as well.
-
-Moving headers and changing library names is fairly straightforward by editing
-CMake code. Mangling symbols usually involves creating a header which has a
-`#define` for each public symbol to change its name at runtime to be distinct
-from another copy that may end up existing in the same process from another
-project.
-
-Typically, a header needs to be created at the module level which hides the
-differences between third party code which may or may not be provided by an
-external package. In this case, it is recommended that code using the third
-party module use unmangled names and let the module interface and mangling
-headers handle the mangling at that level.
-
-### Debugging
-
-The module system can output debugging information about its inner workings by
-using the `_vtk_module_log` variable. This variable is a list of "domains" to
-log about, or the special `ALL` value causes all domains to log output. The
-following domains are used in the internals of the module system:
-
- - `kit`: discovery and membership of kits
- - `module`: discovery and `CONDITION` results of modules
- - `enable`: resolution of the enable status of modules
- - `provide`: determination of module provision
- - `building`: when building a module occurs
- - `testing`: missing test dependencies
-
-It is encouraged that projects expose user-friendly flags to control logging
-rather than exposing `_vtk_module_log` directly.
-
-### Control variables
-
-These variables do not follow the API convention and are used if set:
-
- - `_vtk_module_warnings`: If enabled, "strict" warnings are generated. These
- are not strictly problems, but may be used as linting for improving usage of
- the module system.
- - `_vtk_module_log`: A list of "domains" to output debugging information.
- - `_vtk_module_group_default_${group}`: used to set a non-`DEFAULT` default
- for group settings.
-
-Some mechanisms use global properties instead:
-
- - `_vtk_module_autoinit_include`: The file that needs to be included in order
- to make the `VTK_MODULE_AUTOINIT` symbol available for use in the
- [autoinit](#autoinit) support.
-
-### SPDX files generation
-
-The generation of VTK module SPDX files relies on three components:
-
- - SPDX arguments in {cmake:command}`vtk_module_build`
- - SPDX arguments in each {ref}`vtk.module <module-parse-module>`
- - SPDX Tags in the [sources files](#source-listing)
-
-SPDX files are named after `<ModuleName>.spdx` and are generated for
-all VTK modules.
-
-Generated SPDX files are based on the [SPDX 2.2 specification](https://spdx.dev/specifications/).
-
-If some information is missing, VTK will warn during configuration or during build
-but the SPDX file will still be generated with unknown fields being attributed a
-`NOASSERTION` or other default value.
-
-The collected license identifiers are joined together using `AND` keyword.
-
-Similarly all collected copyright texts are joined using a new line.
-
-#### SPDX arguments in `vtk_module_build`
-
-Support for SPDX file generation requires to specifiy the following
-{cmake:command}`vtk_module_build` arguments:
-
-- `GENERATE_SPDX`
-- `SPDX_DOCUMENT_NAMESPACE`
-- `SPDX_DOWNLOAD_LOCATION`
-
-`GENERATE_SPDX` is used to enable the generation and install of SPDX file for
-each modules. Set this to `ON` to enable it.
-
-`SPDX_DOCUMENT_NAMESPACE` is used as a basename for the `DocumentNamespace`
-SPDX field. The name of the module will simply be appended to the basename.
-If not provided, `https://vtk.org/spdx` will be used. This is the value VTK
-project uses as well. Note that the namespace does not need to be an actual
-website URL, but just a unique Uniform Resource Identifier (URI).
-
-:::{caution}
-If VTK decide to host SPDX files in the future, the namespace in use for the
-VTK SPDX files may change accordingly.
-:::
-
-`SPDX_DOWNLOAD_LOCATION` is used as a basename for the `PackageDownloadLocation`
-when not provided at module level. The relative path to the module will simply
-be appended in order to generate the actual `PackageDownloadLocation` SPDX field.
-If not provided at module or in {cmake:command}`vtk_module_build`, `NOASSERTION`
-will be used.
-
-#### SPDX arguments in `vtk.module`
-
-Defining these three arguments in {ref}`vtk.module <module-parse-module>` is required:
- - `SPDX_LICENSE_IDENTIFIER`
- - `SPDX_COPYRIGHT_TEXT`
- - `SPDX_DOWNLOAD_LOCATION`
-
-`SPDX_LICENSE_IDENTIFIER` is an expected field corresponding to the `PackageLicenseDeclared`
-SPDX field that is considered as the global license for all files of the
-module that are not parsed during generation. This field is used to set
-the `PackageLicenseConcluded` SPDX field.
-
-:::{note}
-The SPDX generation system do not and cannot replace the `LICENSE_FILES` mechanism.
-Indeed, certains license (e.g Apache 2.0) requires additonal files (e.g `NOTICE`) to
-also be distributed.
-:::
-
-`SPDX_COPYRIGHT_TEXT` is an expected field that correspond to the copyright applying
-to all files that are not parsed during generation, it is used to generate `PackageCopyrightText`.
-
-`SPDX_DOWNLOAD_LOCATION` is a optional field for modules (see above for setting
-this in `vtk_module_build`) and expected field for [third parties](/developers_guide/git/thirdparty.md).
-If provided, it is used as is for the `PackageDownloadLocation` SPDX field.
-
-#### Custom license support
-
-If the VTK module contains a custom license that is not part of the [SPDX license list](https://spdx.org/licenses/)
-then adding a custom license may be needed.
-
-The SPDX generation system support to specify exactly one custom license by module, supplemental to standard licenses.
-The text of this license should be made available in a file and added to the module definition using `SPDX_CUSTOM_LICENSE_FILE`
-, the name of the license should be specified using `SPDX_CUSTOM_LICENSE_NAME` (eg: `LicenseName` and the `SPDX_LICENSE_IDENTIFIER` for this license
-should be `LicenseRef-` followed by the name (eg: `LicenseRef-licenseName`). See [this entry](/advanced/spdx_and_sbom.md#frequently_asked_questions) for more info.
-
-:::{note}
-If this custom license is to be added to VTK proper, it must be compatible with the BSD-3-CLAUSE license of VTK and
-not add more restriction to the code.
-:::
-
-#### SPDX Tags in the sources files
-
-For VTK modules (except the one declared as `THIRD_PARTY`), [sources files](#source-listing)
-are parsed for specific SPDX tags in a specific order.
-
-First `N` lines of with the the `SPDX-FileCopyrightText` tag, then one line with
-the `SPDX-License-Identifier` tag. Like this:
-
-```
-// SPDX-FileCopyrightText: Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
-// SPDX-FileCopyrightText: Copyright (c) Awesome contributor
-// SPDX-License-Identifier: BSD-3-CLAUSE
-```
-
-If a source file does not contain both `SPDX-FileCopyrightText` and `SPDX-License-Identifier`
-tags, a CMake warning is reported.
-
-TODO: It would be possible to add a dedicated tag to identify that a file should NOT be parsed for SPDX tags,
-but it is not needed yet.
-
-#### Limitations
-
-* Correctness of the `SPDX-FileCopyrightText` and `SPDX-License-Identifier` tags is not ensured. The value
- will be used as is.
-
-* The generated SPDX files only include the [Package information][spdx-package-information]
- section. This means that there are no [File information][spdx-file-information] sections
- describing source files or build artifacts.
-
-* Third party source files are not parsed for SPDX tags.
-
-[spdx-package-information]: https://spdx.github.io/spdx-spec/v2.2.2/package-information/
-[spdx-file-information]: https://spdx.github.io/spdx-spec/v2.2.2/file-information/
-
-* Adding empty lines between `// SPDX-FileCopyrightText` and `// SPDX-License-Identifier`
- tags is not supported.
-
-* Only comments starting with `//` are considered.
diff --git a/Documentation/Doxygen/PythonWrappers.md b/Documentation/Doxygen/PythonWrappers.md
deleted file mode 100644
index 477e919c3716772495a376975c1c85c2b6e536c3..0000000000000000000000000000000000000000
--- a/Documentation/Doxygen/PythonWrappers.md
+++ /dev/null
@@ -1,1156 +0,0 @@
-# Python Wrappers
-
-## Introduction
-
-This document is a reference for using VTK from Python. It is not a tutorial
-and provides very little information about VTK itself, but instead describes
-in detail the features of the Python wrappers and how using VTK from Python
-differs from using VTK from C++. It assumes that the reader is already
-somewhat familiar with both Python and VTK.
-
-
-## Background
-
-The Python wrappers are automatically generated from the VTK source code,
-and for the most part, there is a one-to-one mapping between the VTK classes
-and methods that you can use from Python and the ones that you can use from
-C++. More specifically, the wrappers are a package of Python extension modules
-that interface directly to the VTK C++ libraries. When you use VTK through
-the wrappers, you are actually executing compiled C++ code, and there is
-very little performance difference between VTK/C++ and VTK/Python.
-
-
-## Installation
-
-VTK for Python can be installed via either conda or pip, where the conda
-packages is maintained on conda-forge, while the pip packages are maintained
-by the VTK developers themselves. If you are first getting started, then pip
-is probably the most convenient way to install VTK for Python:
-
- pip install vtk
-
-This will provide a basic installation of VTK that includes all core
-functionality, but which will not include some of the specialized VTK
-modules that rely on external libraries. Binary packages for VTK can
-also be downloaded directly from https://www.vtk.org/download/.
-
-Instructions for building VTK from source code are given in the file
-[Documentation/dev/build.md][vtk-build] within the source repository.
-
-[vtk-build]: https://gitlab.kitware.com/vtk/vtk/-/blob/release/Documentation/dev/build.md
-
-
-## Importing
-
-VTK is comprised of over one hundred individual modules. Programs can import
-just the modules that are needed, in order to reduce load time.
-
- from vtkmodules.vtkCommonCore import vtkObject
- from vtkmodules.vtkFiltersSources import vtkConeSource, vtkSphereSource
- from vtkmodules.vtkRenderingCore import (
- vtkActor,
- vtkDataSetMapper,
- vtkRenderer,
- vtkRenderWindow
- )
- import vtkmodules.vtkRenderingOpenGL2
-
-When getting started, however, it is hard to know what modules you will need.
-So if you are experimenting with VTK in a Python console, or writing a quick
-and dirty Python script, it is easiest to simply import everything. There
-is a special module called '`all`' that allows this to be done:
-
- from vtkmodules.all import *
-
-After importing the VTK classes, you can check to see which module each of the
-classes comes from:
-
- for c in vtkObject, vtkConeSource, vtkRenderWindow:
- print(f"from {c.__module__} import {c.__name__}")
-
-The output is as follows:
-
- from vtkmodules.vtkCommonCore import vtkObject
- from vtkmodules.vtkFiltersSources import vtkConeSource
- from vtkmodules.vtkRenderingCore import vtkRenderWindow
-
-### Factories and Implementation Modules
-
-In the first 'import' example above, you might be wondering about this line:
-
- import vtkmodules.vtkRenderingOpenGL2
-
-This import is needed because `vtkRenderingOpenGL2` provides the OpenGL
-implementations of the classes in `vtkRenderingCore`. To see this in action,
-open a new Python console and do the following:
-
- >>> from vtkmodules.vtkRenderingCore import vtkRenderWindow
- >>> renwin = vtkRenderWindow()
- >>> type(renwin)
- <class 'vtkmodules.vtkRenderingCore.vtkRenderWindow'>
- >>>
- >>> import vtkmodules.vtkRenderingOpenGL2
- >>> renwin2 = vtkRenderWindow()
- >>> type(renwin2)
- <class 'vtkmodules.vtkRenderingOpenGL2.vtkXOpenGLRenderWindow'>
-
-After `vtkRenderingOpenGL2` has been imported, the `vtkRenderWindow()`
-constructor magically starts returning a different type of object.
-This occurs because `vtkRenderWindow` is a *factory* class, which means that
-the kind of object it produces can be overridden by an *implementation*
-class. In order for the implementation class to do the override, all that
-is necessary is that its module is imported. To make things even more
-confusing, `vtkRenderingOpenGL2` is not the only module that contains
-implementations for the factory classes in `vtkRenderingCore`. The following
-modules are often needed, as well:
-
- import vtkmodules.vtkInteractionStyle
- import vtkmodules.vtkRenderingFreeType
-
-Although you only need implementations for the factory classes that you use,
-it can be hard to know which classes are factory classes, or what modules
-contain implementations for them. Also, it can be difficult to even know
-what classes you are using, since many VTK classes make use of other VTK
-classes. An example of this is `vtkDataSetMapper`, which internally uses
-`vtkPolyDataMapper` to do the rendering. So even though `vtkDataSetMapper` is
-not a factory class, it needs an OpenGL implementation for `vtkPolyDataMapper`.
-
-The simplest approach is to import all the important implementation modules
-into your program, even if you are not certain that you need them.
-* For `vtkRenderingCore`, `import vtkRenderingOpenGL2, vtkRenderingFreeType, vtkInteractionStyle`
-* For `vtkRenderingVolume`, `import vtkRenderingVolumeOpenGL2`
-* For `vtkCharts`, `import vtkContextOpenGL2`
-
-### Classic VTK Import
-
-There are many VTK programs that still import the '`vtk`' module, which
-has been available since VTK 4.0, rather than using the '`vtkmodules`'
-package that was introduced in VTK 8.2:
-
- import vtk
-
-The advantage (and disadvantage) of this is that it imports everything. It
-requires just one import statement for all of VTK, but it can be slow because
-VTK has grown to be very large over the years.
-
-Also note that, between VTK 8.2 and VTK 9.2.5, the use of the `vtk` module
-would confuse the auto-completion features of IDEs such as PyCharm. This
-was fixed in VTK 9.2.6. For 9.2.5 and earlier, the following can be used:
-
- import vtkmodules.all as vtk
-
-From the programmer's perspective, this is equivalent to '`import vtk`'.
-
-## VTK Classes and Objects
-
-### Classes Derived from vtkObjectBase
-
-In C++, classes derived from `vtkObjectBase` are instantiated by calling
-`New()`. In Python, these classes are instantiated by simply calling the
-constructor:
-
- o = vtkObject()
-
-For factory classes, the returned object's type might be a subtype of the
-class. This occurs because the Python wrappers are actually calling `New()`
-for you, which allows the VTK factory overrides to occur:
-
- >>> a = vtkActor()
- >>> type(a)
- <class 'vtkmodules.vtkRenderingOpenGL2.vtkOpenGLActor'>
-
-When you create a VTK object in Python, you are in fact creating two
-objects: a C++ object, and a Python object that holds a pointer to the C++
-object. The `repr()` of the object shows the memory address of the C++
-object (in parentheses) and of the Python object (after the '`at`'):
-
- >>> a = vtkFloatArray()
- >>> a
- <vtkmodules.vtkCommonCore.vtkFloatArray(0x5653a6a6f700) at 0x7f0e7aecf5e0>
-
-If you call `str()` or `print()` on these objects, the wrappers will call the
-C++ `PrintSelf()` method. The printed information can be useful for debugging:
-
- >>> o = vtkObject()
- >>> print(o)
- vtkObject (0x55858308a210)
- Debug: Off
- Modified Time: 85
- Reference Count: 1
- Registered Events: (none)
-
-### Other Classes (Special Types)
-
-VTK also uses several classes that aren't derived from `vtkObjectBase`. The
-most important of these is `vtkVariant`, which can hold any type of object:
-
- >>> v1 = vtkVariant('hello')
- >>> v1
- vtkmodules.vtkCommonCore.vtkVariant('hello')
- >>> v2 = vtkVariant(3.14)
- >>> v2
- vtkmodules.vtkCommonCore.vtkVariant(3.14)
-
-The wrapping of these classes is fully automatic, but is done in a slightly
-different manner than `vtkObjectBase`-derived classes. First, these classes
-have no `New()` method, and instead the public C++ constructors are wrapped
-to create an equivalent Python constructor. Second, the Python object
-contains its own copy of the C++ object, rather than containing just a
-pointer to the C++ object. The vast majority of these classes are lightweight
-containers and numerical types. For example, `vtkQuaterniond`, `vtkRectf`,
-`vtkColor4ub`, etc. Many of them are actually class templates, which are
-discussed below.
-
-When you apply `print()` or `str()` to these objects, the `operator<<` of the
-underlying C++ object is used to print them. For `repr()`, the name of the
-type name is printed, followed by the `str()` output in prentheses. The
-result looks similar to a constructor, though it might look strange depending
-on what `operator<<` produces.
-
- >> v = vtkVariant()
- >> print(repr(v))
- vtkmodules.vtkCommonCore.vtkVariant((invalid))
-
-### Class Templates
-
-There are several C++ templates in VTK, which can be tricky to use from the
-wrappers since the Python language has no real concept of templates. The
-wrappers wrap templates as dictionary-like objects that map the template
-parameters to template instantiations:
-
- >>> vtkSOADataArrayTemplate
- <template vtkCommonCorePython.vtkSOADataArrayTemplate>
- >>> vtkSOADataArrayTemplate.keys()
- ['char', 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'int',
- 'uint', 'int64', 'uint64', 'float32', 'float64']
- >>> c = vtkSOADataArrayTemplate['float64']
- >>> c
- <class 'vtkmodules.vtkCommonCore.vtkSOADataArrayTemplate_IdE'>
-
-The wrappers instantiate the C++ template for a few useful types, as
-indicated by the `keys()` of the template. The Python type name also has a
-suffix (the '`IdE`') that indicates the template parameters in a compressed
-form according to IA64 C++ ABI name mangling rules, even when VTK is built
-with a compiler that does not use the IA64 ABI natively.
-
-Objects are created by first instantiating the template, and then
-instantiating the class:
-
- >>> a = vtkSOADataArrayTemplate['float32']()
- >>> a.SetNumberOfComponents(3)
-
-In the case of multiple template parameters, the syntax can look rather
-complicated, but really it isn't all that bad. For example, constructing
-a `vtkTuple<double,4>` in Python looks like this, with the template
-args in square brackets and the constructor args in parentheses:
-
- >>> vtkTuple['float64',4]([1.0, 2.0, 3.0, 4.0])
- vtkmodules.vtkCommonMath.vtkTuple_IdLi4EE([1.0, 2.0, 3.0, 4.0])
-
-The type names are the same as numpy's dtypes: `bool`, `int8`, `uint8`,
-`int16`, `uint16`, `int32`, `uint32`, `int64`, `uint64`, `float32`, and
-`float64`. Since `int64` is '`long long`', `int` is used for `long`. Also
-see [Template Keys](#template-keys) in [Advanced Topics](#internals-and-advanced-topics).
-
-
-## Method Calls
-
-When VTK methods are called from Python, conversion of all parameters from
-Python to C++ occurs automatically. That is, if the C++ method signature
-expects an integral type, you can pass a Python `int`, and if C++ expects a
-floating-point type, you can pass a Python `float` (or any type that allows
-implicit conversion to `float`).
-
-For C++ '`char`' parameters, which are rarely used in VTK, you must pass a
-string with a length of 1 or 0 bytes. This restricts the value to ASCII,
-since non-ASCII characters require at least 2 bytes in utf-8. An empty
-string signifies a null byte, and '\\0' can also be used.
-
-A Python `tuple`, `list`, or any other Python sequence can be passed to a VTK
-method that requires an array or `std::vector` in C++:
-
- >>> a = vtkActor()
- >>> p = (100.0, 200.0, 100.0)
- >>> a.SetPosition(p)
-
-If the method is going to modify the array that you pass as a parameter,
-then you must pass a Python `list` that has the correct number of slots to
-accept the returned values. If you try this with a `tuple`, you will get a
-`TypeError` because `tuple` is immutable.
-
- >>> z = [0.0, 0.0, 0.0]
- >>> vtkMath.Cross((1,0,0),(0,1,0),z)
- >>> print(z)
- [0.0, 0.0, 1.0]
-
-For multi-dimensional array parameters, you can either use a nested list,
-or you can use numpy array with the correct shape.
-
-If the C++ method returns a pointer to an array, then in Python the method
-will return a tuple if the wrappers know the size of the array. In most
-cases, the size is hinted in the header file.
-
- >>> a = vtkActor()
- >>> print(a.GetPosition())
- (0.0, 0.0, 0.0)
-
-Finally, Python `None` is treated the same as C++ `nullptr`, which allows
-you to pass null objects and null strings:
-
- >>> a = vtkActor()
- >>> a.SetMapper(None)
- >>> print(a.GetMapper())
- None
-
-### Wrappable and Unwrappable Methods
-
-A method cannot be used from Python if its C++ parameters or return type
-cannot be converted to or from Python by the wrappers, or if the method is
-templated. Common non-convertible types include `std::ostream`, `std::istream`,
-and all STL container types except for `std::vector` (see below),
-and any non-trivial pointer type or any pointer to an object whose class is
-not derived from `vtkObjectBase`.
-
-The wrappable parameter types are:
-* `char`, wrapped as a single ASCII character in a Python `str`
-* `signed char` and `unsigned char`, wrapped as Python `int`
-* `short`, `int`, `long` and `long long`, wrapped as Python `int`
-* `unsigned short` to `unsigned long long`, wrapped as Python `int`
-* `float` and `double`, wrapped as Python `float`
-* `size_t` and `ssize_t`, wrapped as Python `int`
-* `std::string`, wrapped as Python `str` via utf-8 encoding/decoding
-* typedefs of all the above, for any typedef defined in a VTK header file
-* `std::vector<T>` where `T` is one of the above, as Python `tuple` or `list`
-* `const T&` where `T` is any of the above, wrapped as described above
-* `T[N]` where `T` is a fundamental type, as Python `tuple` or `list`
-* `T[N][M]` where `T` is a fundamental type, as nested `tuple` or `list`
-* `T*` where `T` is a fundamental type, as `tuple` or `list`
-* `vtkObjectBase*` and derived types, as their respective Python type
-* `vtkSmartPointer<T>` as the Python vtkObjectBase-derived type `T`
-* `std::vector<vtkSmartPointer<T>>` as a sequence of objects of type `T`
-* `const std::vector<vtkSmartPointer<T>>` as a sequence of objects of type `T`
-* other wrapped classes (like `vtkVariant`), but not pointers to these types
-* `char*`, as Python `str` via utf-8 encoding/decoding
-* `void*`, as Python buffer (e.g. `bytes` or `bytearray`)
-* the parameter list `(void (*f)(void*), void*)` as a Python callable type
-
-References like `int&` and `std::string&` are wrapped via a reference proxy
-type as described in the [Pass by Reference](#pass-by-reference) section
-below. Non-const references to `std::vector<T>` and other mutable types
-do not use a proxy, but instead require that a mutable Python object is
-passed, for example a `list` rather than a `tuple`.
-
-A `void*` parameter can accept a pointer in two different ways: either from
-any Python object that supports the Python buffer protocol (this includes
-all numpy arrays along with the Python bytes and bytearray types), or from a
-string that contains a mangled pointer of the form '`_hhhhhhhhhhhh_p_void`'
-where '`hhhhhhhhhhhh`' is the hexadecimal address. Return-value `void*` will
-always be a string containing the mangled pointer.
-
-Also, a `T*` parameter for fundamental type `T` can accept a buffer object,
-if and only if it is annotated with the `VTK_ZEROCOPY` hint in the header file.
-With this hint, a numpy array of `T` can be passed to a `T*` parameter and
-the VTK method will directly access the memory buffer of the array. Hence the
-name 'zerocopy', which indicates no copying is done, and that direct memory
-access is used.
-
-The `vtkObject::AddObserver()` method has a special wrapping, as discussed
-in the [Observer Callbacks](#observer-callbacks) section below.
-
-### Conversion Constructors
-
-If a wrapped type has constructor that takes one parameter, and if that
-constructor is not declared '`explicit`', then the wrappers will automatically
-use that constructor for type conversion to the parameter type. The
-wrappers ensure that this conversion occurs in Python in the same manner
-that it is expected to occur in C++.
-
-For example, `vtkVariantArray` has a method `InsertNextItem(v:vtkVariant)`,
-and `vtkVariant` has a constructor `vtkVariant(x:int)`. So, you can do this:
-
- >>> variantArray.InsertNextItem(1)
-
-The wrappers will automatically construct a `vtkVariant` from '`1`', and
-will then pass it as a parameter to `InsertNextItem()`. This is a feature
-that most C++ programmers will take for granted, but Python users might
-find it surprising.
-
-### Overloaded Methods
-
-If you call a VTK method that is overloaded, the Python wrappers will choose
-the overload that best matches the supplied arguments. This matching takes
-into account all allowed implicit conversions, such as int to float or any
-conversion constructors that are defined for wrapped objects.
-
-Some overloads will be unavailable (not wrapped) either because they are
-unwrappable as per the criteria described above, or because they are shadowed
-by another overload that is always preferable. A simple example of this is
-any methods that is overloaded on C++ `float` and `double`. The Python
-`float` type is a perfect match C++ `double`, therefore the `float` overload
-is not wrapped.
-
-### Static Methods
-
-A static method can be called without an instance. For example,
-
- vtkObject.SetGlobalWarningDisplay(1)
-
-Some VTK classes, like vtkMath, consist solely of static methods. For others,
-like `vtkMatrix4x4`, most of the non-static methods have static overloads.
-Within Python, the only way to tell if a VTK method is static (other than
-trying it) is to look at its docstring.
-
-### Unbound Methods
-
-When a non-static method is called on the class, rather than on an instance,
-it is called an unbound method call. An unbound method call must provide
-'self' as the first argument, where 'self' is an instance of either the class
-or a subclass.
-
- w = vtkRenderWindow()
- vtkWindow.Render(w)
-
-In other words, the wrappers translate Python unbound method calls into
-C++ unbound method calls. These are useful when deriving a Python class
-from a wrapped VTK class, since they allow you to call any base class
-methods that have been overridden in the subclass.
-
-### Operator Methods
-
-For special classes (the ones not derived from `vtkObjectBase`), some useful
-C++ operators are wrapped in python. The '`[]`' operator is wrapped for
-indexing and item assignment, but because it relies on hints to guess which
-indices are out-of-bounds, it is only wrapped for `vtkVector` and related
-classes.
-
-The comparison operators '`<`' '`<=`' '`==`' '`>=`' '`>`' are wrapped for all
-classes that have these operators in C++. These operators allow sorting
-of `vtkVariant` objects with Python.
-
-The '`<<`' operator for printing is wrapped and is used by the python
-`print()` and `str()` commands.
-
-### Strings and Bytes
-
-VTK uses both `char*` and `std::string` for strings. As far as the wrappers
-are concerned, these are equivalent except that the former can be `nullptr`
-(`None` in Python). For both, the expected encoding is ASCII or utf-8.
-
-In Python, either `str` or `bytes` can be used to store strings, and both
-of these can be passed to VTK methods that require `char*` or `std::string`
-(or the legacy `vtkStdString`). A `str` object is passed to VTK as utf-8,
-while a `bytes` object is passed as-is.
-
-When a VTK method returns a string, it is received in Python as a `str` object
-if it is valid utf-8, or as a `bytes` object if not. The caller should check
-the type of the returned object (`str`, `bytes`, or perhaps `None`) if there
-is any reason to suspect that non-utf-8 text might be present.
-
-### STL Containers
-
-VTK provides conversion between `std::vector` and Python sequences
-such as `tuple` and `list`. If the C++ method returns a vector,
-the Python method will return a tuple:
-
- C++: const std::vector<std::string>& GetPaths()
- C++: std::vector<std::string> GetPaths()
- Python: GetPaths() -> Tuple[str]
-
-If the C++ method accepts a vector, then the Python method can be
-passed any sequence with compatible values:
-
- C++: void SetPaths(const std::vector<std::string>& paths)
- C++: void SetPaths(std::vector<std::string> paths)
- Python: SetPaths(paths: Sequence[str]) -> None
-
-Furthermore, if the C++ method accepts a non-const vector reference,
-then the Python method can be passed a mutable sequence (e.g. `list`):
-
- C++: void GetPaths(std::vector<std::string>& paths)
- Python: GetPaths(paths: MutableSequence[str]) -> None
-
-The value type of the `std::vector<T>` must be `std::string` or a
-fundamental numeric type such as `double` or `int` (including
-`signed char` and `unsigned char` but excluding `char`).
-
-### Smart pointers
-
-The wrappers will automatically convert between C++ `vtkSmartPointer<T>`
-and objects of type `T` (or `None`, if the smart pointer is empty):
-
- C++: vtkSmartPointer<vtkObject> TakeObject()
- Python: TakeObject() -> vtkObject
-
-In other words, in Python the smart pointer doesn't look any different
-from the object it points to. Under the hood, however, the wrappers
-understand that the smart pointer carries a reference to the object and
-will take responsibility for deleting that reference.
-
-A C++ method can return a vector of smart pointers, which will be seen in
-Python as a tuple of objects:
-
- C++: std::vector<vtkSmartPointer<vtkObject>> GetObjects()
- Python: GetObject() -> Tuple[vtkObject]
-
-If a C++ method expects `std::vector<vtkSmartPointer<T>>` as a parameter,
-the wrappers will automatically construct the vector from any sequence that
-is passed from Python. The objects in the sequence must be of type `T` (or
-a subclass of `T`, or `None`). If not, a `TypeError` will be raised.
-
-### Pass by Reference
-
-Many VTK methods use pass-by-reference to return values back to the caller.
-Calling these methods from Python requires special consideration, since
-Python's `str`, `tuple`, `int`, and `float` types are immutable. The wrappers
-provide a '`reference`' type, which is a simple container that allows
-pass-by-reference.
-
-For example, consider the following C++ method that uses pass-by-reference:
-
- void GetCellAtId(vtkIdType cellId, vtkIdType& cellSize, vtkIdType const*& cellPoints)
-
-It requires a reference to `vtkIdType` (a Python `int`), and to
-`vtkIdType const*` (a tuple of `int`s). So we can call this method as
-follows:
-
- >>> from vtkmodules.vtkCommonCore import reference
- >>> from vtkmodules.vtkCommonDataModel import vtkCellArray
- >>>
- >>> # Build a cell array
- >>> a = vtkCellArray()
- >>> a.InsertNextCell(3, (1, 3, 0))
- >>>
- >>> # Create the reference objects
- >>> n = reference(0)
- >>> t = reference((0,))
- >>>
- >>> # Call the pass-by-reference method
- >>> a.GetCellAtId(0, n, t)
- >>>
- >>> n.get()
- 3
- >>> t.get()
- (1, 3, 0)
-
-Some important notes when using pass-by-reference:
-1. The reference constructor must be given a value of the desired type.
- The method might use this value or might ignore it.
-2. Calling the `get()` method of the reference is usually unnecessary,
- because the reference already supports the interface protocols of the
- object that it contains.
-
-### Preconditions
-
-One very real concern when using VTK from Python is that the parameters that
-you pass to a method might cause the program to crash. In particular, it is
-very easy to pass an index that causes an out-of-bounds memory access, since
-the C++ methods don't do bounds checking. As a safety precaution, the
-wrappers perform the bounds check before the C++ method is called:
-
- >>> a = vtkFloatArray()
- >>> a.GetValue(10)
- Traceback (most recent call last):
- File "<stdin>", line 1, in <module>
- ValueError: expects 0 <= id && id < GetNumberOfValues()
-
-All precondition checks raise a `ValueError` if they fail, since they are
-checks on the values of the parameters. The wrappers don't know if C++ is
-using the parameter as an index, so `IndexError` is not used.
-
-Currently the only way to find out if a method has preconditions is to look
-at the declaration of the method in the C++ header file to see if it has a
-`VTK_EXPECTS` hint.
-
-## Observer Callbacks
-
-Similar to what can be done in C++, a Python function can be called
-each time a VTK event is invoked on a given object. In general, the
-callback function should have the signature `func(obj:vtkObject, event:str)`,
-or `func(self, obj:vtkObject, event:str)` if it is a method of a class.
-
- >>> def onObjectModified(object, event):
- >>> print('object: %s - event: %s' % (object.GetClassName(), event))
- >>>
- >>> o = vtkObject()
- >>> o.AddObserver(vtkCommand.ModifiedEvent, onObjectModified)
- 1
- >>> o.Modified()
- object: vtkObject - event: ModifiedEvent
-
-
-### Call Data
-
-In case there is a 'CallData' value associated with an event, in C++, you
-have to cast it from `void*` to the expected type using `reinterpret_cast`.
-The equivalent in python is to add a `CallDataType` attribute to the
-associated python callback method. The supported `CallDataType` values are
-`VTK_STRING`, `VTK_OBJECT`, `VTK_INT`, `VTK_LONG`, `VTK_DOUBLE`, and
-`VTK_FLOAT`.
-
-The following example uses a function as a callback, but a method or any
-callable object can be used:
-
- >>> from vtkmodules.vtkCommonCore import vtkCommand, VTK_INT
- >>>
- >>> def onError(object, event, calldata):
- >>> print('object: %s - event: %s - msg: %s' % (object.GetClassName(), event, calldata))
- >>>
- >>> onError.CallDataType = VTK_INT
- >>>
- >>> lt = vtkLookupTable()
- >>> lt.AddObserver(vtkCommand.ErrorEvent, onError)
- 1
- >>> lt.SetTableRange(2,1)
- object: vtkLookupTable - event: ErrorEvent - msg: ERROR:
- In /home/user/VTK/Common/Core/vtkLookupTable.cxx, line 122
- vtkLookupTable (0x6b40b30): Bad table range: [2, 1]
-
-For convenience, the `CallDataType` can also be specified where the function
-is first declared with the help of the `@calldata_type` decorator:
-
- >>> from vtkmodules.util.misc import calldata_type
- >>>
- >>> @calldata_type(VTK_INT)
- >>> def onError(object, event, calldata):
- >>> print('object: %s - event: %s - msg: %s' % (object.GetClassName(),
- event, calldata))
-
-## Other Wrapped Entities
-
-### Constants
-
-Most of the constants defined in the VTK header files are available in Python,
-and they can be accessed from the module in which they are defined. Many of
-these are found in the `vtkCommonCore` module, where they were defined as
-preprocessor macros.
-
- >>> from vtkmodules.vtkCommonCore import VTK_DOUBLE_MAX
- >>> VTK_DOUBLE_MAX
- 1.0000000000000001e+299
-
-Others are defined as enums, often within a class namespace. If the enum
-is anonymous, then its values are `int`.
-
- >>> vtkCommand.ErrorEvent
- 39
-
-Constants in the header files are wrapped if they are enums, or if they are
-const variables of a wrappable scalar type, or if they are preprocessor
-symbols that evaluate to integer, floating-point, or string literal types.
-
-### Enum Types
-
-Each named enum type is wrapped as a new Python type, and members of the enum
-are instances of that type. This allows type checking for enum types:
-
- >>> from vtkmodules.vtkCommonColor import vtkColorSeries
- >>> vtkColorSeries.COOL
- 2
- >>> isinstance(vtkColorSeries.ColorSchemes, vtkColorSeries.COOL)
- >>> cs = vtkColorSeries()
- >>> cs.SetColorScheme(vtkColorSeries.COOL)
-
-Enum classes are wrapped in a manner similar to named enums, except that
-the enum values are placed within the enum class namespace. For example,
-`vtkEventDataAction` is an enum class, with '`Press`' as a member:
-
- >>> from vtkmodules.vtkCommonCore import vtkEventDataAction
- >>> vtkEventDataAction.Press
- 1
- >>> isinstance(vtkEventDataAction.Press, vtkEventDataAction)
- True
-
-In the first example, the `ColorSchemes` enum type and the `COOL` enum value
-were both defined in the `vtkColorSeries` namespace. In the second example,
-the `vtkEventDataAction` enum class was defined in the module namespace,
-and the `Press` value was defined in the enum class namespace.
-
-Note that the VTK enum types behave like C++ enums, and not like the Python
-enums types provided by the Python '`enum`' module. In particular, all VTK
-enum values can be used anywhere that an `int` can be used.
-
-### Namespaces
-
-Namespaces are currently wrapped in a very limited manner. The only
-namespace members that are wrapped are enum constants and enum types.
-There is no wrapping of namespaced classes or functions, or of nested
-namespaces. Currently, the wrappers implement namespaces as Python
-`module` objects.
-
-
-## Docstrings
-
-The wrappers automatically generate docstrings from the doxygen comments in
-the header files. The Python `help()` command can be used to print the
-documentation to the screen, or the `__doc__` attributes of the classes
-and methods can be accessed directly.
-
-### Method Docstrings
-
-The method docstrings are formatted with the method signatures first,
-followed by doxygen comments. The Python method signatures have type
-annotations, and are followed by the C++ method signatures for
-completeness.
-
-```
- InvokeEvent(self, event:int, callData:Any) -> int
- C++: int InvokeEvent(unsigned long event, void* callData)
- InvokeEvent(self, event:str, callData:Any) -> int
- C++: int InvokeEvent(const char* event, void* callData)
- InvokeEvent(self, event:int) -> int
- C++: int InvokeEvent(unsigned long event)
- InvokeEvent(self, event:str) -> int
- C++: int InvokeEvent(const char* event)
-
- This method invokes an event and returns whether the event was
- aborted or not. If the event was aborted, the return value is 1,
- otherwise it is 0.
-```
-
-Some Python IDEs will automatically show the docstring as soon as you type
-the name of the method.
-
-### Class Docstrings
-
-The class docstrings include a brief description of the class, followed
-by the name of the superclass, and then the full doxygen documentation,
-including doxygen markup:
-
-```
- vtkMatrix4x4 - represent and manipulate 4x4 transformation matrices
-
- Superclass: vtkObject
-
- vtkMatrix4x4 is a class to represent and manipulate 4x4 matrices.
- Specifically, it is designed to work on 4x4 transformation matrices
- found in 3D rendering using homogeneous coordinates [x y z w]. Many
- of the methods take an array of 16 doubles in row-major format. Note
- that OpenGL stores matrices in column-major format, so the matrix
- contents must be transposed when they are moved between OpenGL and
- VTK.
- @sa
- vtkTransform
-```
-
-If the class is not derived from `vtkObjectBase`, then it will have one or
-more public constructors, and these will be included before the comments:
-
-```
- vtkSimpleCriticalSection() -> vtkSimpleCriticalSection
- C++: vtkSimpleCriticalSection()
- vtkSimpleCriticalSection(isLocked:int) -> vtkSimpleCriticalSection
- C++: vtkSimpleCriticalSection(int isLocked)
-
- vtkSimpleCriticalSection - Critical section locking class
-
- vtkCriticalSection allows the locking of variables which are accessed
- through different threads.
-```
-
-### Template Docstrings
-
-Class templates are documented similar to classes, except that they include
-a 'Provided Types' section that lists the available template instantiations
-and the C++ template arguments that they correspond to.
-
-```
- vtkSOADataArrayTemplate - Struct-Of-Arrays implementation of
- vtkGenericDataArray.
-
- Superclass: vtkGenericDataArray[vtkSOADataArrayTemplate[ValueTypeT],ValueTypeT]
-
- vtkSOADataArrayTemplate is the counterpart of vtkAOSDataArrayTemplate.
- Each component is stored in a separate array.
-
- @sa
- vtkGenericDataArray vtkAOSDataArrayTemplate
-
-
- Provided Types:
-
- vtkSOADataArrayTemplate[char] => vtkSOADataArrayTemplate<char>
- vtkSOADataArrayTemplate[int8] => vtkSOADataArrayTemplate<signed char>
- vtkSOADataArrayTemplate[uint8] => vtkSOADataArrayTemplate<unsigned char>
- vtkSOADataArrayTemplate[int16] => vtkSOADataArrayTemplate<short>
- vtkSOADataArrayTemplate[uint16] => vtkSOADataArrayTemplate<unsigned short>
- vtkSOADataArrayTemplate[int32] => vtkSOADataArrayTemplate<int>
- vtkSOADataArrayTemplate[uint32] => vtkSOADataArrayTemplate<unsigned int>
- vtkSOADataArrayTemplate[int] => vtkSOADataArrayTemplate<long>
- vtkSOADataArrayTemplate[uint] => vtkSOADataArrayTemplate<unsigned long>
- vtkSOADataArrayTemplate[int64] => vtkSOADataArrayTemplate<long long>
- vtkSOADataArrayTemplate[uint64] => vtkSOADataArrayTemplate<unsigned long long>
- vtkSOADataArrayTemplate[float32] => vtkSOADataArrayTemplate<float>
- vtkSOADataArrayTemplate[float64] => vtkSOADataArrayTemplate<double>
-```
-
-Unlike classes, the template documentation is formatted similarly regardless
-of whether the the class template derives from `vtkObjectBase` or not:
-
-```
- vtkVector - templated base type for storage of vectors.
-
- Superclass: vtkTuple[T,Size]
-
- This class is a templated data type for storing and manipulating fixed
- size vectors, which can be used to represent two and three dimensional
- points. The memory layout is a contiguous array of the specified type,
- such that a float[2] can be cast to a vtkVector2f and manipulated. Also
- a float[6] could be cast and used as a vtkVector2f[3].
-
-
- Provided Types:
-
- vtkVector[float64,4] => vtkVector<double, 4>
- vtkVector[float32,4] => vtkVector<float, 4>
- vtkVector[int32,4] => vtkVector<int, 4>
- vtkVector[float64,2] => vtkVector<double, 2>
- vtkVector[float32,2] => vtkVector<float, 2>
- vtkVector[int32,2] => vtkVector<int, 2>
- vtkVector[float64,3] => vtkVector<double, 3>
- vtkVector[float32,3] => vtkVector<float, 3>
- vtkVector[int32,3] => vtkVector<int, 3>
-```
-
-
-## Internals and Advanced Topics
-
-### Special Attributes
-
-Classes and objects derived from `vtkObjectBase` have special attributes, which
-are only used in very special circumstances.
-
-The `__vtkname__` attribute of the class provides the same string that the
-GetClassName() method returns. With the exception of classes that are
-template instantiations, it is identical to the `__name__` attribute.
-For template instantiations, however, `GetClassName()` and `__vtkname__`
-return the result of calling `typeid(cls).name()` from C++, which provides
-a platform specific result:
-
- >>> vtkSOADataArrayTemplate['float32'].__vtkname__
- '23vtkSOADataArrayTemplateIfE'
-
-This can be used to get the VTK `ClassName` when you don't have an
-instantiation to call `GetClassName()` on. It is useful for checking the
-type of a C++ VTK object against a Python VTK class.
-
-The `__this__` attribute of the objects is a bit less esoteric, it provides a
-pointer to the C++ object as a mangled string:
-
- >>> a = vtkFloatArray()
- >>> a.__this__
- '_00005653a6a6f700_p_vtkFloatArray'
-
-The string provides the hexadecimal address of '`this`', followed by '`p`'
-(shorthand for *pointer*), and the type of the pointer. You can also
-construct a Python object directly from the C++ address, if the address is
-formatted as described above:
-
- >>> a = vtkFloatArray('_00005653a6a6f700_p_vtkFloatArray')
- >>> a
- <vtkmodules.vtkCommonCore.vtkFloatArray(0x5653a6a6f700) at 0x7f0e7aecf5e0>
-
-If you call the constructor on the string provided by `__this__`, you will
-get exactly the same Python object back again, rather than a new object.
-But this constructor can be useful if you have some VTK code that has been
-wrapped with a different wrapper tool, for example with SWIG. If you can
-get the VTK pointer from SWIG, you can use it to construct Python object
-that can be used with the native VTK wrappers.
-
-### Wrapper Hints
-
-A wrapper hint is an attribute that can be added to a class, method, or
-parameter declaration in a C++ header file to give extra information to
-the wrappers. These hints are defined in the `vtkWrappingHints.h` header
-file.
-
-The following hints can appear before a method declaration:
-* `VTK_WRAPEXCLUDE` excludes a method from the wrappers
-* `VTK_NEWINSTANCE` passes ownership of a method's return value to the caller
-
-For convenience, `VTK_WRAPEXCLUDE` can also be used to exclude a whole class.
-The `VTK_NEWINSTANCE` hint is used when the return value is a `vtkObjectBase*`
-and the caller must not increment the reference count upon acceptance of the
-object (but must still decrement the reference count when finished with the
-object).
-
-The following hints can appear after a method declaration:
-* `VTK_EXPECTS(cond)` provides preconditions for the method call
-* `VTK_SIZEHINT(expr)` marks the array size of a return value
-* `VTK_SIZEHINT(name, expr)` marks the array size of a parameter
-
-For `VTK_EXPECTS(cond)`, the precondition must be valid C++ code, and can
-use any of the parameter names or `this`. Even without `this`, any public
-names in the class namespace (including method names) will be resolved.
-See the [Preconditions](#preconditions) section for additional information.
-
-`VTK_SIZEHINT(expr)` is used for methods that return an array as type `T*`,
-where `T` is a numeric data type. The hint allows the wrappers to convert the
-array to a tuple of the correct size. Without the size hint, the wrappers
-will return the pointer as a string that provides a mangled memory address
-of the form '`_hhhhhhhhhhhh_p_void`' where '`hhhhhhhhhhhh`' is address
-expressed in hexadecimal.
-
-`VTK_SIZEHINT(parameter_name, expr)` is used to hint parameters of type
-`T*` or `T&*` (with `T` as a numeric data type) so that the wrappers know
-the size of the array that the pointer is pointing to. The `expr` can be
-any expression that evaluates to an integer, and it can include parameter
-names, public class members and method calls, or the special name `_`
-(underscore) which indicates the method's return value. In the absence
-of a size hint, the wrappers cannot check that the length of the sequence
-passed from Python matches the size of the array required by the method.
-If the method requires a larger array than it receives, a buffer overrun
-will occur.
-
-The following hints can appear before a parameter declaration:
-* `VTK_FILEPATH` marks a parameter that accepts a pathlib.Path object
-* `VTK_ZEROCOPY` marks a parameter that accepts a buffer object
-
-More specifically, `VTK_FILEPATH` is used with `char*` and `std::string`
-parameters to indicate that the method also accepts any object with a
-`__fspath__()` method that returns a path string. And `VTK_ZEROCOPY` is
-used with `T*` parameters, for basic integer or float type `T`, to indicate
-that the Python buffer protocol will be used to access the values, rather
-than the Python sequence protocol that is used by default.
-
-### Deprecation Warnings
-
-In addition to the wrapping hints, the Python wrappers are also aware of the
-deprecation attributes that have been applied to classes and methods. When
-a deprecated method is called, a `DeprecationWarning` is generated and
-information about the deprecation is printed, including the VTK version
-for the deprecation.
-
-To ignore these warnings, use the following code:
-
- import warnings
- warnings.filterwarnings('ignore', category=DeprecationWarning)
-
-To see each deprecation warning just once per session,
-
- warnings.filterwarnings('once', category=DeprecationWarning)
-
-### Template Keys
-
-The following is a table of common template key names, which are the same as
-the numpy dtype names. Note that you can actually use numpy dtypes as keys,
-as well as the native Python types `bool`, `int`, and `float`. There is
-some danger in using `int`, however, because it maps to C++ `long` which has
-a platform-dependent size (either 32 bits or 64 bits). Finally, the char
-codes from the Python `array` module can be used as keys, but they should
-be avoided since more programmers are familiar with numpy than with the
-much older `array` module.
-
-| C++ Type | Template Key | Type Key | Char Key | IA64 ABI Code |
-| ------------------ | ------------ | -------- | -------- | ------------- |
-| bool | 'bool' | bool | '?' | IbE |
-| char | 'char' | | 'c' | IcE |
-| signed char | 'int8' | | 'b' | IaE |
-| unsigned char | 'uint8' | | 'B' | IhE |
-| short | 'int16' | | 'h' | IsE |
-| unsigned short | 'uint16' | | 'H' | ItE |
-| int | 'int32' | | 'i' | IiE |
-| unsigned int | 'uint32' | | 'I' | IjE |
-| long | 'int' | int | 'l' | IlE |
-| unsigned long | 'uint' | | 'L' | ImE |
-| long long | 'int64' | | 'q' | IxE |
-| unsigned long long | 'uint64' | | 'Q' | IyE |
-| float | 'float32' | | 'f' | IfE |
-| double | 'float64' | float | 'd' | IdE |
-
-Since the size of '`long`' and '`unsigned long`' is platform-dependent, these
-types should generally be avoided.
-
-### Exception Handling
-
-There are times when an observer might generate a Python exception. Since
-the observers are called from C++, there is no good way to catch these
-exceptions from within Python. So, instead, the wrappers simply print a
-traceback to stderr and then clear the error indicator. The Python program
-will continue running unless the exception was a `KeyboardInterrupt` (Ctrl-C),
-in which case the program will exit with an error code of 1.
-
-### Deleting a vtkObject
-
-There is no direct equivalent of VTK's `Delete()` method, since Python does
-garbage collection automatically. The Python object will be deleted
-when there are no references to it within Python, and the C++ object will
-be deleted when there are no references to it from within either Python
-or C++. Note that references can hide in unexpected places, for example if
-a method of an object is used as an observer callback, the object will not
-be deleted until the observer is disconnected.
-
-The `DeleteEvent` can be used to detect object deletion, but note that the
-observer will receive a None for the object, since the observer is called
-after (not before) the deletion occurs:
-
- >>> o = vtkObject()
- >>> o.AddObserver('DeleteEvent', lambda o,e: print(e, o))
- 1
- >>> del o
- DeleteEvent None
-
-If you need to know what object is deleted, the identifying information must
-be extracted before the deletion occurs:
-
- >>> o = vtkObject()
- >>> o.AddObserver('DeleteEvent',lambda x,e,r=repr(o): print(e, r))
- 1
- >>> del o
- DeleteEvent <vtkmodules.vtkCommonCore.vtkObject(0x55783870f970) at 0x7f1e61678be0>
-
-In cases where you need to track down tricky memory issues, you might find
-it useful to call the `GetReferenceCount()` method of the object directly.
-
-### Ghosts
-
-A wrapped VTK object (derived from `vtkObjectBase`) is a Python object that
-holds a pointer to a C++ object (specifically, a `vtkObjectBase*`). The
-Python object can have attributes that the C++ object knows nothing about.
-So, what happens to these attributes if the Python object is deleted, but
-the C++ object lives on? Consider this simple example of storing the C++
-object in an array and then deleting the Python object:
-
- obj = vtkObject()
- obj.tag = 'FirstObject'
- va = vtkVariantArray()
- va.InsertNextValue(obj)
- del obj
-
-When we retrieve the object from the array, we want it to have the '`tag`'
-attributes that it had we stored it. But you might wonder, aren't all
-Python-specific attributes deleted along with the Python object? The
-answer is, no they aren't, they're saved until until the C++ object itself
-is deleted.
-
-The wrappers have a special place, which we will call the graveyard, where
-'ghosts' of objects are stored when the objects are deleted. The ghost is not
-an object, but rather a container for the Python attributes of a deceased
-object. If the object ever reappears within Python, usually as a return
-value from a C++ method call, then the ghost is resurrected as a new Python
-object that has all the attributes of the original Python object.
-
-The graveyard is only used for objects that have unfinished business. If a
-Python object has an empty dict and no other special attributes, then it will
-not go to the graveyard. Also, if the C++ object is deleted at the same time
-as the Python object, then the graveyard will not be used. Each ghost in the
-graveyard holds a weak pointer to its C++ object and will vanish when the C++
-object is deleted (not immediately, but the next time the graveyard garbage
-collector runs).
-
-### Subclassing a VTK Class
-
-It is possible to subclass a VTK class from within Python, but this is of
-limited use because the C++ virtual methods are not hooked to the Python
-methods. In other words, if you make a subclass of `vtkPolyDataAlgorithm`
-and override override the `Execute()` method, it will not be automatically
-called by the VTK pipeline. Your `Execute()` method will only be called if
-the call is made from Python.
-
-The addition of virtual method hooks to the wrappers has been proposed,
-but currently the only way for Python methods to be called from C++ code
-is via callbacks. The `vtkProgrammableSource` and `vtkProgrammableFilter` are
-examples of VTK algorithm classes that use callbacks for execution, while
-`vtkInteractionStyleUser` can use observer callbacks for event handling.
-
-### Wrapping External VTK Modules
-
-If you have your own C++ classes that are based on VTK, and if they are
-placed with a VTK module with a vtk.module file, then they can be wrapped
-as shown in the [Module Wrapping Example][external-wrapping]. You will
-also find the cmake documentation on VTK modules to be useful.
-
-[external-wrapping]: https://gitlab.kitware.com/vtk/vtk/-/blob/release/Examples/Modules/Wrapping
-
-## Experimental Features
-
-### Python Class Overrides
-
-VTK now supports overriding wrapped classes with Python subclasses. This
-enables developers to provide more Python friendly interfaces for certain
-classes. Here is a trivial example of an override:
-
- from vtkmodules.vtkCommonCore import vtkPoints
- @vtkPoints.override
- class CustomPoints(vtkPoints):
- pass
-
-Once the override is in place, any future `vtkPoints` Python object instances
-will be instances of the override class. This behavior is global.
-
- points = vtk.vtkPoints() # returns an instance of CustomPoints
-
-The override can be reversed by setting an override of `None`, but this will
-not impact instantiations that have already occurred.
-
- vtkPoints.override(None)
-
-If the class has already been overridden in C++ via VTK's object factory
-mechanism, then directly applying a Python override to that class will not
-work. Instead, the Python override must be applied to the C++ factory
-override. For example, on Windows,
-
- @vtkWin32OpenGLRenderWindow.override
- class CustomRenderWindow(vtkWin32OpenGLRenderWindow):
- ...
- window = vtkRenderWindow() # creates a CustomRenderWindow
-
-Please see [Subclassing a VTK Class](#subclassing-a-vtk-class) for restrictions on
-subclassing VTK classes through Python.
-
-
-### Stub Files for Type Hinting
-
-VTK includes a script called [`generate_pyi.py`][generate_pyi] that
-will generate pyi stub files for each wrapped VTK module. The purpose of
-these files, as explained in [PEP 484][pep_484], is to provide type
-information for all constants, classes, and methods in the modules.
-Each of these files contain blocks like this:
-
- VTK_DOUBLE:int
- VTK_DOUBLE_MAX:float
- VTK_DOUBLE_MIN:float
- ...
-
- class vtkObject(vtkObjectBase):
- def AddObserver(self, event:int, command:Callback, priority:float=0.0) -> int: ...
- def GetMTime(self) -> int: ...
- @staticmethod
- def GetNumberOfGenerationsFromBaseType(type:str) -> int: ...
- @overload
- def HasObserver(self, event:int, __b:'vtkCommand') -> int: ...
- @overload
- def HasObserver(self, event:str, __b:'vtkCommand') -> int: ...
-
- class vtkAbstractArray(vtkObject):
- class DeleteMethod(int): ...
- VTK_DATA_ARRAY_ALIGNED_FREE:'DeleteMethod'
- VTK_DATA_ARRAY_DELETE:'DeleteMethod'
- VTK_DATA_ARRAY_FREE:'DeleteMethod'
- VTK_DATA_ARRAY_USER_DEFINED:'DeleteMethod'
- def Allocate(self, numValues:int, ext:int=1000) -> int: ...
-
-Python consoles like ipython and IDEs like PyCharm can use the information in
-these files to provide hints while you edit the code. These files are
-included in the Python packages for VTK, but they can also be built by
-executing the `generate_pyi.py` script. To do so, execute the script
-with the `vtkpython` executable (or with the regular python executable,
-if its paths are set for VTK):
-
- vtkpython -m vtkmodules.generate_pyi
-
-This will place build the pyi files and place them inside the `vtkmodules`
-package, where ipython and PyCharm should automatically find them. The
-help for this script is as follows:
-
- usage: python generate_pyi.py [-p package] [-o output_dir] [module ...]
- options:
- -p NAME Package name [vtkmodules by default].
- -o OUTPUT Output directory [package directory by default].
- -e EXT Output file suffix [.pyi by default].
- module Module or modules to process [all by default].
-
-The pyi files are syntactically correct python files, so it is possible to
-load them as such in order to test them and inspect them.
-
-[generate_pyi]: https://gitlab.kitware.com/vtk/vtk/-/blob/release/Wrapping/Python/vtkmodules/generate_pyi.py
-[pep_484]: https://www.python.org/dev/peps/pep-0484/#stub-files
diff --git a/Documentation/Doxygen/SMPTools.md b/Documentation/Doxygen/SMPTools.md
deleted file mode 100644
index 1a25801d21e6c30c392e2b387cf6fb4286fe63a6..0000000000000000000000000000000000000000
--- a/Documentation/Doxygen/SMPTools.md
+++ /dev/null
@@ -1,320 +0,0 @@
-# Parallel Processing with VTK's SMP Framework
-August 2022
-
-## Contributors
-Berk Geveci wrote the initial version of this document in 2013. The design and implementation of vtkSMPTools was strongly influenced by the [KAAPI thread scheduling system](https://www.researchgate.net/publication/221564735_KAAPI_A_thread_scheduling_runtime_system_for_data_flow_computations_on_cluster_of_multi-processors) and an associated Inria research report: [*VtkSMP: Task-based Parallel Operators for Accelerating VTK Filters*](https://hal.inria.fr/hal-00789814). Later contributors to this document include:
-- Timothee Couble
-- Charles Gueunet
-- Will Schroeder
-- Spiros Tsalikis
-
-Also note that several blog posts have been written about vtkSMPTools:
-- [Simple, Parallel Computing with vtkSMPTools](https://www.kitware.com/simple-parallel-computing-with-vtksmptools/)
-- [VTK Shared Memory Parallelism Tools, 2021 updates](https://www.kitware.com/vtk-shared-memory-parallelism-tools-2021-updates/)
-- [Ongoing VTK / ParaView Performance Improvements](https://www.kitware.com/ongoing-vtk-paraview-performance-improvements/)
-- [VTK/ParaView Filters: Performance Improvements](https://www.kitware.com/vtk-paraview-filters-performance-improvements/)
-
-## Introduction
-The overarching objective of vtkSMPTools, the SMP (symmetric multiprocessing) framework, is to provide an infrastructure to simplify the development of shared memory parallel algorithms in VTK. In addition, vtkSMPTools defines a simple, abstract API that drives several threading backends such as std::thread, TBB (i.e., Intel's Threading Building Blocks template library); and OpenMP; as well as supporting a sequential backend for testing and debugging. To achieve these objectives, we have developed three simple constructs to support basic SMP functionality:
-
-- Parallel building blocks / functions
-- Thread local storage
-- Atomic integers and associated operations. (Note, since C++11 this has been superseded by `std::atomic<>`. Also, `std::mutex` and `vtkAtomicMutex` are options.)
-
-vtkSMPTools is extremely easy to use, ensuring that the major challenge of creating parallel algorithms is not one of implementation, but rather the design of good, threaded algorithms. In the next sections we describe the basic concepts used in vtkSMPTools, and then demonstrate these concepts through example code. Of course, there are hundreds of vtkSMPTools implementations found in VTK which provide an excellent source of more complex examples. In the final section of this document we provide tips on how to design and implement vtkSMPTools-based algorithms.
-
-## Concepts
-
-The following are several high-level concepts that will help you understand and use vtkSMPTools.
-
-### The Age of Abundant Computing Cores
-Many early computational algorithms were designed and implemented in an era of limited computing resources: typically a single CPU was available with rudimentary memory models. Such limitations typically led to a frugal approach to writing algorithms, in particular approaches that minimized CPU utilization. However modern computing architectures commonly have many cores with multiple execution threads per core, and memory models have expanded to include a hierarchy of data caches to retrieve frequently used data more quickly. Also, many developers are inclined to think in terms of *sequential* algorithmic operations, partly due to the way in which we were trained but also because managing multiple simultaneous processes can take a lot of work and programmers are often pressed for time. But with growing data sizes, increasing computational demands, and the abundance of computing threads; it's clear that parallel approaches are essential to creating responsive and impactful software tools. It's important that VTK developers conceive and implement performant parallel algorithms to ensure that the system remain vital into the future.
-
-There are a variety of approaches to parallel computing, but two approaches - distributed computing and shared memory computing - are particularly relevant to VTK. In distributed computing, computational tasks are carried out in separate memory space and exchange information through message passing communication. In shared memory computing, information is exchanged through variables in shared memory space. Typically a flavor of MPI is used by VTK for distributed computing, plus VTK provides a variety of software constructs to support distributed computing. vtkSMPTools is used to implement shared memory computing with symmetric multiprocessing (SMP) approaches; i.e., where multiple processors are connected to a single, shared memory space. Distributed computing is more complex and scales best for extremely large data, while shared memory computing is simpler and works cell on single computers (desktop, laptop, mobile). Note that it is possible to combine distributed and shared computing in a VTK application.
-
-Besides MPI (for distributed computing) and vtkSMPTools (shared memory parallelism, typically on CPUs), be aware that VTK leverages another parallel processing toolkit for computing accelerators (e.g., GPUs). [vtk-m](https://m.vtk.org/) is a toolkit of scientific visualization algorithms for emerging processor architectures, supporting fine-grained concurrency for data analysis and visualization algorithms. Depending on the application, vtk-m may be a preferred solution for extreme scale computing. It is possible to mix all three forms of parallel computing frameworks into a single VTK application.
-
-### Fine- and Coarse-Grained Parallelism
-When parallelizing an algorithm, it is important to first consider the "dimension" (i.e., the way in which data is accessed via threads) over which to parallelize it. For example, VTK's Imaging modules parallelize many algorithms by assigning subsets of the input image (VOIs) to a thread safe function which processes them in parallel. Another example is parallelizing over blocks of a composite dataset (such as an AMR dataset). We refer to these examples as coarse-grained parallelism. On the other hand, we can choose points or cells as a dimension over which to parallelize access to a VTK dataset. Many algorithms simply loop over cells or points and are relatively trivial to parallelize this way. Here we refer to this approach as fine-grained parallelism. Note that some algorithms fall into a gray area. For example, if we parallelize streamline generation over seeds, is it fine- or coarse-grained parallelism?
-
-### Backends
-The SMP framework provides a thin abstraction over a number of threading backends. Currently, we support four backends: Sequential (serial execution); C++ std::thread referred to as STDThread; TBB (based on Intel’s TBB); and OpenMP. Note that the Sequential backend is useful for debugging but is typically not used unless no other backend can be made to work on the target platform. As discussed in the following, it's possible to build VTK with multiple backends, and switch between them at run-time.
-
-Backends are configured via CMake during the build process. Setting the CMake variables `VTK_SMP_ENABLE_OPENMP`, `VTK_SMP_ENABLE_SEQUENTIAL`, `VTK_SMP_ENABLE_STDTHREAD`, and `VTK_SMP_ENABLE_TBB` enables the inclusion of the appropriate SMP backend(s), and `VTK_SMP_IMPLEMENTATION_TYPE` can be used to select one of Sequential, OpenMP, TBB, and STDThread (this selects the default backend when VTK runs). Once VTK is built, setting the environment variable `VTK_SMP_BACKEND_IN_USE` can be used to select from multiple backends. (Note: `vtkSMPTools::SetBackend()` can be used from within a C++ application to select the backend as well -- for example `vtkSMPTools::SetBackend("TBB")` will select TBB.)
-
-### Thread Safety in VTK
-Probably the most important thing in parallelizing shared-memory algorithms is to make sure that all operations that occur in a parallel region are performed in a thread-safe way (i.e., avoid race conditions). Note that there is much in the VTK core functionality that is not thread-safe. The VTK community has an ongoing effort of cleaning this up and marking APIs that are thread-safe to use. At this point, probably the best approach is to double check by looking at the implementation. Also, we highly recommend using analysis tools such as ThreadSanitizer or Valgrind (with the Helgrind tool) to look for race conditions in problematic code.
-
-When coding parallel algorithms, be especially wary of insidious execution side effects. Such side effects typically result in simultaneous execution of code. For example, invoking `Update()` on a filter shared by multiple threads is a bad idea since simultaneous updates to that filter is likely doomed to fail. Also, some methods like `vtkPolyData::GetCellNeighbors()` internally invoke the one-time operation `BuildLinks()` in order to generate topological information. Similarly, the `BuildLocator()` method found in point and cell locators may be called as a side effect of a geoemtric query such as `vtkDataSet::FindCell()`. In such cases, prior to threaded execution, affected classes should be "primed" by explicitly invoking methods that produce side effects (e.g., call `BuildLinks()` directly on the `vtkPolyData`; or manually call `BuildLocator()` prior to using methods that require a locator).
-
-### Results Invariance
-A significant challenge to writing good threaded algorithms is to insure that they produce the same output each time they execute. For example, a threaded sort operation may order *identical* set elements differently each time the sort is run depending on the order in which data is processed by different computing threads. (This is related to the C++ standard providing the `std::stable_sort` algorithm.) Even simple threaded operation such as summing a list of numbers can produce different results, since the order and partitioning of data during threading may result in round off effects. Since sequential algorithms implicitly order their operations, and threading typically does not do so (unless extensive use of locks, barriers, etc. are used), a sequential algorithm may produce different results than a threaded algorithm, and even across multiple runs threaded algorithms may produce results that vary across each run. Such behaviors are disturbing to users, and make testing difficult. In VTK, we aim to write algorithms that are results invariant.
-
-### Show Me the Code
-The vtkSMPTools class defined in `VTK\Common\Core\vtkSMPTools.h` provides detailed documentation and further implementation details. To find examples of vtkSMPTools in use, simply search for VTK C++ classes that include this header file.
-
-## Implementation Overview
-As mentioned previously, vtkSMPTools provides a few, simple programmatic building blocks; support for thread-local storage; and support for atomics. In this section we provide high-level descriptions of these building blocks. Then in the following section we provide implementation details.
-
-### Functional Building Blocks
-The core, functional building blocks of vtkSMPTools are as follows. See `vtkSMPTools.h` for details.
-* `For(begin, end, functor)` - a for loop over the range [begin,end) executing the functor each time.
-* `Fill(begin, end, value)` - assign the given value to the elements in range [begin,end) (a drop in replacement for `std::fill()`).
-* `Sort(begin,end)` and `Sort(begin,end,compare)` - sort the elements in range [begin,end) using the optional comparison function (a drop in replacement for `std::sort()`).
-* `Transform()` - a drop in replacement for `std::transform()`.
-
-Note that the ranges [begin,end) may be expressed via integral (`vtkIdType`) types for example point or cell ids, or C++ iterators.
-
-Of special interest is the `functor` invoked in the `For()` loop. The functor is a class/struct which requires defining the `void operator()(begin,end)` method. Given a range defined by `[begin, end)` and the functor, `For()` will call the functor’s `operator()`, usually in parallel, over a number of subranges of `[begin, end)`. The functor may also implement methods to initialize data associated with each thread (`void Initialize()`), and to composite the results of executing the `For()` loop into a final result (i.e., `void Reduce()`).
-
-With these few building blocks, powerful threaded algorithms can easily be written. In many cases, the `For()` loop is all that is needed.
-
-### Thread Local Storage
-Often times parallel algorithms produce intermediate results that are combined to produce a final result. For example, to sum a long list of numbers, each thread may sum just a subset of the numbers, and when completed the intermediate sums from each thread can be combined to produce a final summation. So the ability to maintain intermediate data associated with each thread is valuable. This is the purpose of thread local storage.
-
-Thread local storage is generally referred to memory that is accessed by one thread only. In the SMP framework, vtkSMPThreadLocal and vtkSMPThreadLocalObject enable the creation of objects local to executing threads. The main difference between the two is that vtkSMPThreadLocalObject makes it easy to manage vtkObject and subclasses by allocating and deleting them appropriately. Thread local storage almost always requires definition of the `Initialize()` and `Reduce()` methods to initialize local storage, and then combine it once the `For()` loop completes.
-
-One important performance trick with thread local storage, is that temporary variables may be defined and then used in the execution of `operator()`. For example, instantiating temporary objects such as vtkGenericCell, vtkIdList, and other C++ containers or classes can be relatively slow. Sometimes it's much faster to create and initialize them once (when the thread is created), and then "reset" them in each invocation of `operator()`.
-
-### Atomics
-Another very useful tool when developing shared memory parallel algorithms is atomic integers. Atomic integers provide the ability to manipulate integer values in a way that can’t be interrupted by other threads. A very common use case for atomic integers is implementing global counters. For example, in VTK, the modified time (MTime) global counter and vtkObject’s reference count are implemented as atomic integers.
-
-Prior to C++11, vtkSMPTools had an internal implementation for atomic integers. However, this implementation is now obsolete in favor of `std::atomic<>`. C++ also provides `std::mutex' and 'std::lock_guard<>`; and VTK provides a lightweight spinlock `vtkAtomicMutex` which may be faster than using mutexes.
-
-## Implementation Examples
-In the subsections below, we describe the SMP framework in more detail and provide examples of how it can be used.
-
-### Functors and Parallel For
-The `vtkSMPTools::For()` parallel for is the core computational construct of vtkSMPTools. It's use is as shown in the following example which evaluates points against a set of planes, and adjusts the planes to "bound" the points (see `vtkHull.cxx` and `VTK/Common/DataModel/Testing/Cxx/TestSMPFeatures.cxx`).
-```
- vtkNew<vtkPoints> pts;
- pts->SetDataTypeToFloat();
- pts->SetNumberOfPoints(numPts);
- for ( auto i=0; i < numPts; ++i)
- {
- pts->SetPoint(i, vtkMath::Random(-1,1), vtkMath::Random(-1,1), vtkMath::Random(-1,1));
- }
-```
-Now define the functor:
-```
-struct HullFunctor
-{
- vtkPoints *InPts;
- std::vector<double>& Planes;
-
- HullFunctor(vtkPoints *inPts, std::vector<double>& planes) : InPts(inPts), Planes(planes) {}
-
- void operator()(vtkIdType ptId, vtkIdType endPtId)
- {
- vtkPoints *inPts = this->InPts;
- std::vector<double>& planes = this->Planes;
- auto numPlanes = planes.size() / 4;
-
- for (; ptId < endPtId; ++ptId)
- {
- double v, coord[3];
- inPts->GetPoint(ptId, coord);
- for (size_t j = 0; j < numPlanes; j++)
- {
- v = -(planes[j * 4 + 0] * coord[0] + planes[j * 4 + 1] * coord[1] +
- planes[j * 4 + 2] * coord[2]);
- // negative means further in + direction of plane
- if (v < planes[j * 4 + 3])
- {
- planes[j * 4 + 3] = v;
- }
- }
- }
- }
-}; //HullFunctor
-```
-To use the functor and invoke `vtkSMPTools::For()`:
-```
- HullFunctor hull(pts,planes);
- vtkSMPTools::For(0,numPts, hull);
-```
-Note that same code can be conveniently and compactly defined inline via a C++ lambda function. Lambdas are particularly useful when thread local storage and/or local variable are not required.
-```
- vtkSMPTools::For(0, numPts, [&](vtkIdType ptId, vtkIdType endPtId) {
- for (; ptId < endPtId; ++ptId)
- {
- double v, coord[3];
- pts->GetPoint(ptId, coord);
- for (auto j = 0; j < numPlanes; j++)
- {
- v = -(planes[j * 4 + 0] * coord[0] + planes[j * 4 + 1] * coord[1] +
- planes[j * 4 + 2] * coord[2]);
- // negative means further in + direction of plane
- if (v < planes[j * 4 + 3])
- {
- planes[j * 4 + 3] = v;
- }
- }
- }
- }); // end lambda
-```
-With alternative signatures for `For()` it is possible to provide a grain parameter. Grain is a hint to the underlying backend about the coarseness of the typical range when parallelizing a for loop. If you don’t know what grain will work best for a particular problem, omit the grain specification and let the backend find a suitable grain. TBB in particular does a good job with this. Sometimes, you can eek out a little bit more performance by setting the grain just right. Too small, the task queuing overhead will be too much. Too little, load balancing will suffer.
-
-### Thread Local Storage
-Thread local storage is generally referred to memory that is accessed by one thread only. In the SMP framework, vtkSMPThreadLocal and vtkSMPThreadLocalObject enable the creation objects local to executing threads. The main difference between the two is that vtkSMPThreadLocalObject makes it easy to manage vtkObject and subclasses by allocating and deleting them appropriately.
-
-Below is an example of thread local objects in use. This example computes the bounds of a set of points represented by a vtkFloatArray. Note in particular the introduction of the `Initialize()` and `Reduce()` methods:
-```
-using BoundsArray = std::array<double,6>;
-using TLS = vtkSMPThreadLocal<BoundsArray>;
-
-struct BoundsFunctor
-{
- vtkFloatArray* Pts;
- BoundsArray Bounds;
- TLS LocalBounds;
-
- BoundsFunctor(vtkFloatArray *pts) : Pts(pts) {}
-
- // Initialize thread local storage
- void Initialize()
- {
- // The first call to .Local() will create the array,
- // all others will return the same.
- std::array<double,6>& bds = this->LocalBounds.Local();
- bds[0] = VTK_DOUBLE_MAX;
- bds[1] = -VTK_DOUBLE_MAX;
- bds[2] = VTK_DOUBLE_MAX;
- bds[3] = -VTK_DOUBLE_MAX;
- bds[4] = VTK_DOUBLE_MAX;
- bds[5] = -VTK_DOUBLE_MAX;
- }
-
- // Process the range of points [begin,end)
- void operator()(vtkIdType begin, vtkIdType end)
- {
- BoundsArray& lbounds = this->LocalBounds.Local();
- float* x = this->Pts->GetPointer(3*begin);
- for (vtkIdType i=begin; i<end; i++)
- {
- lbounds[0] = (x[0] < lbounds[0] ? x[0] : lbounds[0]);
- lbounds[1] = (x[0] > lbounds[1] ? x[0] : lbounds[1]);
- lbounds[2] = (x[1] < lbounds[2] ? x[1] : lbounds[2]);
- lbounds[3] = (x[1] > lbounds[3] ? x[1] : lbounds[3]);
- lbounds[4] = (x[2] < lbounds[4] ? x[2] : lbounds[4]);
- lbounds[5] = (x[2] > lbounds[5] ? x[2] : lbounds[5]);
-
- x += 3;
- }
- }
-
- // Composite / combine the thread local storage into a global result.
- void Reduce()
- {
- this->Bounds[0] = VTK_DOUBLE_MAX;
- this->Bounds[1] = -VTK_DOUBLE_MAX;
- this->Bounds[2] = VTK_DOUBLE_MAX;
- this->Bounds[3] = -VTK_DOUBLE_MAX;
- this->Bounds[4] = VTK_DOUBLE_MAX;
- this->Bounds[5] = -VTK_DOUBLE_MAX;
-
- using TLSIter = TLS::iterator;
- TLSIter end = this->LocalBounds.end();
- for (TLSIter itr = this->LocalBounds.begin(); itr != end; ++itr)
- {
- BoundsArray& lBounds = *itr;
- this->Bounds[0] = (this->Bounds[0] < lBounds[0] ? this->Bounds[0] : lBounds[0]);
- this->Bounds[1] = (this->Bounds[1] > lBounds[1] ? this->Bounds[1] : lBounds[1]);
- this->Bounds[2] = (this->Bounds[2] < lBounds[2] ? this->Bounds[2] : lBounds[2]);
- this->Bounds[3] = (this->Bounds[3] > lBounds[3] ? this->Bounds[3] : lBounds[3]);
- this->Bounds[4] = (this->Bounds[4] < lBounds[4] ? this->Bounds[4] : lBounds[4]);
- this->Bounds[5] = (this->Bounds[5] > lBounds[5] ? this->Bounds[5] : lBounds[5]);
- }
- }
-}; // BoundsFunctor
-```
-Then to use the functor:
-```
- vtkFloatArray* ptsArray = vtkFloatArray::SafeDownCast(pts->GetData());
- BoundsFunctor calcBounds(ptsArray);
- vtkSMPTools::For(0, numPts, calcBounds);
- std::array<double,6>& bds = calcBounds.Bounds;
-```
-
-A few things to note here:
-* LocalBounds.Local() will return a new instance of a `std::vector<std::vector<double>>` per thread the first time it is called by that thread. All calls afterwards will return the same instance for that thread. Therefore, threads can safely access the local object over and over again without worrying about race conditions.
-* The `Initialize()` method initializes the new instance of the thread local vector with invalid bound values.
-
-So at the end of the threaded computation, the `LocalBounds` will contain a number of arrays, each that was populated by one thread during the parallel execution. These still need to be composited to produce the global bounds. This can be achieved by iterating over all thread local values and combining them in the `Reduce()` method as shown previously. Consequently the user can simply retrieve the final bounds by accessing `calcBounds.Bounds` once `vtkSMPTools::For()` completes execution. Note that, if the methods exist, `Initialize()` and `Reduce()` are invoked automatically by `vtkSMPTools::For()`.
-
-Very important note: if you use more than one thread local storage object, don’t assume that the iterators will traverse them in the same order. The iterator for one may return the value from thread i with begin() whereas the other may return the value form thread j. If you need to store and access values together, make sure to use a struct or class to group them.
-
-Thread local objects are immensely useful. Often, visualization algorithms want to accumulate their output by appending to a data structure. For example, the contour filter iterates over cells and produces polygons that it adds to an output vtkPolyData. This is usually not a thread safe operation. One way to address this is to use locks that serialize writing to the output data structure.
-
-However, mutexes have a major impact on the scalability of parallel operations. Another solution is to produce a different vtkPolyData for each execution of the functor. However, this can lead to hundreds if not thousands of outputs that need to be merged, which is a difficult operation to scale. The best option is to use one vtkPolyData per thread using thread local objects. Since it is guaranteed that thread local objects are accessed by one thread at a time (but possibly in many consecutive functor invocations), it is thread safe for functors to keep adding polygons to these objects. The result is that the parallel section will produce only a few vtkPolyData, usually the same as the number of threads in the pool. It is much easier to efficiently merge these vtkPolyData.
-
-### Atomic Integers
-As mentioned previously, atomics should be represented by the C++ std::atomic<>. However, to provide a brief explanation of the importance of atomics we provide the following simple example.
-
-```
-int Total = 0;
-std::atomic<vtkTypeInt32> TotalAtomic(0);
-constexpr int Target = 1000000;
-constexpr int NumThreads = 2;
-
-VTK_THREAD_RETURN_TYPE MyFunction(void *)
-{
- for (int i=0; i<Target/NumThreads; i++)
- {
- ++Total;
- ++TotalAtomic;
- }
- return VTK_THREAD_RETURN_VALUE;
-}
-
-// Now exercise atomics
-vtkNew<vtkMultiThreader> mt;
-mt->SetSingleMethod(MyFunction, NULL);
-mt->SetNumberOfThreads(NumThreads);
-mt->SingleMethodExecute();
-std::cout << Total << " " << TotalAtomic.load() << endl;
-```
-
-When this program is executed, most of the time `Total` will be different (smaller) than `Target` whereas `TotalAtomic` will be exactly the same as `Target`. For example, a test run on a Mac prints: `999982 1000000`. This is because when the integer is not atomic, both threads can read the same value of `Total`, increment and write out the same value, which leads to losing one increment operation. Whereas, when ++ happens atomically, it is guaranteed that it will read, increment and write out `Total` all in one uninterruptible operation. When atomic operations are supported at hardware level, they are very fast.
-
-## Tips
-In this section, we provide some tips that we hope will be useful to those that want to develop shared memory parallel algorithms.
-
-### Think about Thread Safety
-First things first, it is essential to keep thread safety in mind. If the parallel section does not produce correct results consistently, there is not a lot of point in the performance improvement it produces. To create thread-safe algorithms, consider using common parallel design patterns. Also verify that the API you are using is thread safe under your particular application. While VTK continues to add additional thread-safe capabilities, there are still many booby traps to avoid.
-
-### Analysis Tools Are Your Friend
-The LLVM/Clang-based ThreadSanitizer is widely used to detect data races. Valgrind’s Helgrind is also a wonderful tool. Use these tools often. We developed the original backends mainly using Helgrind. Note that backends like TBB can produce many false positives; you may want to try different backends to reduce these. There are commercial tools with similar functionality, e.g., Intel’s Parallel Studio has static and dynamic checking.
-
-### Debugging Tricks
-Beyond using the analysis tools mentioned previously (e.g., ThreadSanitizer), there are some simple tricks that can be used to resolve programming issues relatively quickly. Firstly, switch between different backends. For example, if a program runs correctly when the backend is set to Sequential, but incorrectly when the backend is other than Sequential, it's likely that there is a race condition. Such broken code, when run repeatedly, while not always failing at the same point due to the variability of thread execution, will often fail at or near the same function, providing clues as to the location of the race. Also, empirically the STDThread backend seems to be most sensitive to race conditions. So make sure to test with more than one backend especially STDThread.
-
-### Avoid Locks
-Mutexes are expensive. Avoid them as much as possible. Mutexes are usually implemented as a table of locks by the kernel. They take a lot of CPU cycles to acquire. Specially, if multiple threads want to acquire them in the same parallel section. Use atomic integers if necessary. Try your best to design your algorithm without modifying the same data concurrently.
-
-### Use Atomics Sparingly
-Atomics are very useful and much more efficient that mutexes. However, overusing them may lead to performance issues. Try to design your algorithm in a way that you avoid locks and atomics. This also applies to using VTK classes that manipulate atomic integers such as MTime and reference count. Try to minimize operations that cause MTime or shared reference counts to change in parallel sections.
-
-### Grain Can Be Important
-In some situation, setting the right value for grain may be important. TBB does a decent job with this but there are situations where it can’t do the optimal thing. There are a number of documents on setting the grain size with TBB on the Web. If you are interested in tuning your code further, we recommend taking a look at some of them.
-
-### Minimize Data Movement
-This is true for serial parts of your code too but it is specially important when there are bunch of threads all accessing main memory. This can really push the limits of the memory bus. Code that is not very intensive computationally compared to how much memory it consumes is unlikely to scale well. Good cache use helps of course but may not be always sufficient. Try to group work together in tighter loops.
-
-### Choose Computation over Memory
-As mentioned earlier in this document, typically computation is much cheaper than data movement. As a result, it's a good idea to create compact data structures with minimal representational fat. Such data structures may require computation to extract important information: for example, a data structure that contains a vector 3-tuple need not represent the vector magnitude since this can be quickly computed. Depending on the number of times vector magnitude is needed, the cost of computing it is usually less than the cost of placing vector magnitude into memory. Of course, effects like this are a function of scale / data size and must be considered when designing applications.
-
-### Multi-Pass Implementations
-Parallel algorithms often require significant bookkeeping to properly partition and transform input data to output data. Trivial algorithms, such as mapping an input vector array of 3-tuples to an output scalar array of vector magnitudes, are easy to partition and map: for each vector tuple, a single scalar is produced; and if there are N tuples, there are N scalars. However, more complex algorithms such as building cell links (creating lists of cells connected to a point) or smoothing stencils (identifying points connected to each other via a cell edge) require an initial pass to determine the size of output arrays (and then to allocate the output), followed by another pass to actually populate the output arrays. While at first counterintuitive, it turns out that allocating a small number of large memory blocks is much, much faster than many dynamic allocations of small amounts of memory. This is one reason that a common implementation pattern for parallel algorithms is to use multiple data processing passes consisting of simple computing operations. Such an approach is quite different than many serial algorithms that often perform multiple, complex algorithmic steps for each input data item to be processed.
-
-A variation of this approach is to use thread local storage to perform computation on a local range of input, store the result in thread local, and then reduce/composite the local storage into the global output. While this is problematic for many reasons (especially since data movement is needed to composite the output data), it still can be used to effectively partition and transform input data to the output, especially if the thread local storage is relatively small in size.
-
-Whatever approach is used, parallel algorithms are often implemented using multiple passes. When designing parallel algorithms, it is important to think in terms of passes, and implement algorithms accordingly.
-
-### Use Parallel Design Patterns
-There are many parallel operations that are used repeatedly. Of course `for` loops and `fill()` are two obvious operations, but the `sort()` operation is more widely used than might be expected. Another is the prefix sum (or inclusive scan, or simply scan) typically used to build indices into data arrays. Become familiar with these and other parallel operations and the task of designing and implementing algorithms will be much easier.
-
-## Parallel Is Not Always Faster
-Threading introduces overhead into computation. As a result, threaded computation is not always faster than an equivalent serial operation. For example, `for` loops across a small number of data items can easily slow down computation due to **thread creation overhead**. A simple addition on each entry of an array may become a bottleneck if done using a too fine grain, due to **false sharing** (threads continuously invalidating other thread's cache). Even complex operations such as prefix sums across large amounts of data may be slower than serial implementations because of **synchronization issues**. For this reason, use threading sparingly to address data or computation of large scale. In VTK it is not uncommon to see code that switches between serial and parallel implementations based on input data size.
-
-Different backends may have significantly performance characteristics as well. TBB for example uses a thread pool combined with task stealing to address load balancing challenges. Empirically at the time of writing, in some situations TBB can significantly outperform the STDThread backend especially in situations where task loads are highly variable. Of course this may change as std::thread implementations mature and evolve.
diff --git a/Documentation/dev/build.md b/Documentation/dev/build.md
deleted file mode 100644
index 6edc8780a56495fa2733cbda7661d59cad9ffe45..0000000000000000000000000000000000000000
--- a/Documentation/dev/build.md
+++ /dev/null
@@ -1,274 +0,0 @@
-# Building
-
-This page describes how to build and install VTK. It covers building for
-development, on both Unix-type systems (Linux, HP-UX, Solaris, macOS), and
-Windows. Note that Unix-like environments such as Cygwin and MinGW are not
-officially supported. However, patches to fix problems with these platforms
-will be considered for inclusion. It is recommended that users which require
-VTK to work on these platforms to submit nightly testing results for them.
-
-A full-featured build of VTK depends on several open source tools and libraries
-such as Python, Qt, CGNS, HDF5, etc. Some of these are included in the VTK
-source itself (e.g., HDF5), while others are expected to be present on the
-machine on which VTK is being built (e.g., Python, Qt).
-
-VTK supports all of the common generators supported by CMake. The Ninja,
-Makefiles, and Visual Studio generators are the most well-tested however.
-
-Note that VTK does not support in-source builds, so you must have a build tree
-that is not the source tree.
-
-## Obtaining the sources
-
- There are two approaches:
-
-::::{tab-set}
-
-:::{tab-item} Release Download
-1. Download the source release `VTK-X.Y.Z.tar.gz` from https://vtk.org/download/.
-2. Create a folder for VTK.
-3. Extract the contents of the VTK folder in the downloaded archive to the subfolder called `source`
-:::
-
-:::{tab-item} Git Clone
-To obtain VTK's sources locally, clone the VTK repository using [Git][git].
-
-[git]: https://git-scm.org
-
-Open `Git Bash` on Windows or a terminal on Linux and macOS and
-execute the following:
-
-```sh
-mkdir -p ~/vtk
-git clone --recursive https://gitlab.kitware.com/vtk/vtk.git ~/vtk/source
-```
-:::
-
-::::
-
-To use the latest features being developed or to make changes and
-contribute to VTK, download the source using **Git Clone**.
-
-## Prerequisites
-
-VTK only requires a few packages in order to build in general, however
-specific features may require additional packages to be provided to VTK's
-build configuration.
-
-Required:
-
- * [CMake][cmake]
- - Version 3.12 or newer, however, the latest version is always recommended.
- If the system package management utilities do not offer cmake or if the offered version is too old
- Precompiled binaries available on [CMake's download page][cmake-download].
-
- * Supported compiler
- - GCC 4.8 or newer
- - Clang 3.3 or newer
- - Apple Clang 7.0 (from Xcode 7.2.1) or newer
- - Microsoft Visual Studio 2015 or newer
- - Intel 14.0 or newer
-
-### Optional Additions
-
-- **ffmpeg**
- When the ability to write `.avi` files is desired, and writing these files is
- not supported by the OS, VTK can use the ffmpeg library. This is generally
- true for Unix-like operating systems. Source code for ffmpeg can be obtained
- from [the website][ffmpeg].
-
-- **MPI**
- To run VTK in parallel, an [MPI][mpi] implementation is required. If an MPI
- implementation that exploits special interconnect hardware is provided on your
- system, we suggest using it for optimal performance. Otherwise, on Linux/Mac,
- we suggest either [OpenMPI][openmpi] or [MPICH][mpich]. On Windows, [Microsoft
- MPI][msmpi] is required.
-
-- **Python**
- In order to use scripting, [Python][python] is required. The minimum supported version is **3.4**.
- The instructions are using the system Python. On Ubuntu/Debian the required package is
- `python3-dev`. If you use a different Python
- implementation or a virtual environment make sure the environment you use is
- activated. On Ubuntu/Debian the required package for creating virtual environments is
- `python3-venv`.
-
-- **Qt5**
- VTK uses Qt as its GUI library (if the relevant modules are enabled).
- Precompiled binaries are available on [Qt's website][qt-download].
- Note that on Windows, the compiler used for building VTK must match the
- compiler version used to build Qt. Version **5.9** or newer is required.
-
-- **OSMesa**
- Off-screen Mesa can be used as a software-renderer for running VTK on a server
- without hardware OpenGL acceleration. This is usually available in system
- packages on Linux. For example, the `libosmesa6-dev` package on Debian and
- Ubuntu. However, for older machines, building a newer version of Mesa is
- likely necessary for bug fixes and support. Its source and build instructions
- can be found on [its website][mesa].
-
-[cmake]: https://cmake.org
-[cmake-download]: https://cmake.org/download
-[ffmpeg]: https://ffmpeg.org
-[mpi]: https://www.mcs.anl.gov/research/projects/mpi
-[mpich]: https://www.mpich.org
-[msmpi]: https://docs.microsoft.com/en-us/message-passing-interface/microsoft-mpi
-[openmpi]: https://www.open-mpi.org
-[python]: https://python.org
-[qt-download]: https://download.qt.io/official_releases/qt
-[mesa]: https://www.mesa3d.org
-
-## Creating the Build Environment
-
-::::{tab-set}
-
-:::{tab-item} Windows
-
- * Install CMake
-
- * Install [Visual Studio Community Edition][visual-studio]
-
- * During installation select the "desktop development with C++" workload.
-
- * Use "x64 Native Tools Command Prompt" for the installed Visual Studio
- version to configure with CMake and to build with ninja.
-
- * Get [ninja][ninja]. Unzip the binary and put it in `PATH`. Note that newer
- Visual Studio releases come with a version of `ninja` already and should
- already exist in `PATH` within the command prompt.
-
-[ninja]: https://ninja-build.org
-[visual-studio]: https://visualstudio.microsoft.com/vs
-
-:::
-
-:::{tab-item} Linux (Ubuntu/Debian)
-
-Install the following packages:
-
-```bash
-$ sudo apt install \
-build-essential \
-cmake \
-cmake-curses-gui \
-mesa-common-dev \
-mesa-utils \
-freeglut3-dev \
-ninja-build
-```
-:::
-
-:::{tab-item} macOS
-
-* Install CMake
-
-* Install XCode
-
-* Ensure XCode command line tools are installed:
-
-```bash
-xcode-select --install
-```
-:::
-
-::::
-
-```{note}
-`ninja` is a more efficient alternative to `Makefiles` or Visual Studio solution files. The
-speed increase is the most noticeable when doing incremental build.
-```
-
-## Configure
-
-In order to build, CMake requires two steps, configure and build. VTK itself
-does not support what are known as in-source builds, so the first step is to
-create a build directory.
-
-::::{tab-set}
-
-:::{tab-item} Windows (Ninja)
-
-Open "x64 Native Tools Command Prompt" for the installed Visual Studio:
-
-```sh
-ccmake -GNinja -S %HOMEPATH%\vtk\source -B %HOMEPATH%\vtk\build
-```
-
-Note that CMake GUI must also be launched from the "Native Tools Command Prompt".
-
-:::
-
-:::{tab-item} Windows (Visual Studio)
-
-Use CMake to generate a Visual Studio solution file (`.sln`).
-
-1. Open CMake GUI, either by typing `cmake-gui` on the command prompt or from the start-menu.
-2. Enter the source and build directories
-3. Click `[Configure]`
-4. You will now get a selection screen in which you can specify your "generator". Select the one you need.
-5. We are now presented with a few options that can be turned on or off as desired.
-6. Click `[Configure]` to apply the changes.
-7. Click `[Generate]`. This will populate the "build" sub-folder.
-8. Finally, click `[Open Project]` to open the generated solution in Visual Studio.
-
-:::
-
-:::{tab-item} Linux/macOS
-
-```sh
-mkdir -p ~/vtk/build
-cd ~/vtk/build
-ccmake -GNinja ../path/to/vtk/source
-```
-
-The parameter `-GNinja` may be skipped to use the default generator (e.g `Unix Makefiles`).
-:::
-
-::::
-
-```{admonition} **Missing dependencies**
-:class: warning
-
-CMake may not find all dependencies automatically in all cases. The steps
-needed to find any given package depends on the package itself.
-
-For general assistance, please see the documentation for
-[`find_package`'s search procedure][cmake-find_package-search] and
-[the relevant Find module][cmake-modules-find] (as available).
-
-[cmake-find_package-search]: https://cmake.org/cmake/help/latest/command/find_package.html#search-procedure
-[cmake-modules-find]: https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html#find-modules
-```
-:::{hint}
-Different features can be enabled/disabled by setting the [Build Settings](build_settings.md) during the configure stage.
-:::
-
-## Building
-
-To build VTK:
-
-::::{tab-set}
-
-:::{tab-item} Windows (Ninja)
-
-```sh
-cmake --build %HOMEPATH%\vtk\build --config Release
-```
-:::
-
-:::{tab-item} Windows (Visual Studio)
-
-Open the generated solution file.
-
-1. Set the configuration to "Release"
-
-2. On the menu bar, choose `Build`, and then choose `Build Solution`.
-:::
-
-:::{tab-item} Linux/macOS
-
-```sh
-cmake --build ~/vtk/build
-```
-:::
-
-::::
diff --git a/Documentation/dev/build_settings.md b/Documentation/dev/build_settings.md
deleted file mode 100644
index 0e36e5cb69ddb3ae98fea0d013e20c12ece4d72a..0000000000000000000000000000000000000000
--- a/Documentation/dev/build_settings.md
+++ /dev/null
@@ -1,291 +0,0 @@
-# Build Settings
-
-VTK has a number of settings available for its build. The common variables
-to modify include:
-
- * `BUILD_SHARED_LIBS` (default `ON`): If set, shared libraries will be
- built. This is usually what is wanted.
- * `VTK_USE_CUDA` (default `OFF`): Whether [CUDA][cuda] support will be available or
- not.
- * `VTK_USE_MPI` (default `OFF`): Whether [MPI][mpi] support will be available or
- not.
- * `VTK_WRAP_PYTHON` (default `OFF`; requires `VTK_ENABLE_WRAPPING`): Whether
- Python support will be available or not.
-
-Less common, but variables which may be of interest to some:
-
- * `VTK_BUILD_EXAMPLES` (default `OFF`): If set, VTK's example code will be
- added as tests to the VTK test suite.
- * `VTK_ENABLE_LOGGING` (default `ON`): If set, enhanced logging will be
- enabled.
- * `VTK_LOGGING_TIME_PRECISION` (default `3`; requires `VTK_ENABLE_LOGGING`):
- Change the precision of times output when `VTK_ENABLE_LOGGING` is on.
- * `VTK_BUILD_TESTING` (default `OFF`): Whether to build tests or not. Valid
- values are `OFF` (no testing), `WANT` (enable tests as possible), and `ON`
- (enable all tests; may error out if features otherwise disabled are
- required by test code).
- * `VTK_ENABLE_KITS` (default `OFF`; requires `BUILD_SHARED_LIBS`): Compile
- VTK into a smaller set of libraries. Can be useful on platforms where VTK
- takes a long time to launch due to expensive disk access.
- * `VTK_ENABLE_WRAPPING` (default `ON`): Whether any wrapping support will be
- available or not.
- * `VTK_WRAP_JAVA` (default `OFF`; requires `VTK_ENABLE_WRAPPING`):
- Whether Java support will be available or not.
- * `VTK_SMP_IMPLEMENTATION_TYPE` (default `Sequential`): Set which SMPTools
- will be implemented by default. Must be either `Sequential`, `STDThread`,
- `OpenMP` or `TBB`. The backend can be changed at runtime if the desired
- backend has his option `VTK_SMP_ENABLE_<backend_name>` set to `ON`.
- * `VTK_ENABLE_CATALYST` (default `OFF`): Enable the CatlystConduit module
- and build the VTK Catalyst implementation. Depends on an external Catalyst.
-
-OpenGL-related options:
-
-Note that if OpenGL is used, there must be a "sensible" setup. Sanity checks
-exist to make sure a broken build is not being made. Essentially:
-
-- at least one rendering environment (X, Cocoa, SDL2, OSMesa, EGL, etc.) must
- be available;
-- OSMesa and EGL conflict with each other; and
-- OSMesa only supports off-screen rendering and is therefore incompatible with
- Cocoa, X, and SDL2.
-
- * `VTK_USE_COCOA` (default `ON`; requires macOS): Use Cocoa for
- render windows.
- * `VTK_USE_X` (default `ON` for Unix-like platforms except macOS,
- iOS, and Emscripten, `OFF` otherwise): Use X for render windows.
- * `VTK_USE_SDL2` (default `ON` for Emscripten, `OFF` otherwise): Use
- SDL2 for render windows.
- * `VTK_OPENGL_HAS_OSMESA` (default `OFF`): Use to indicate that the
- OpenGL library being used supports offscreen Mesa rendering
- (OSMesa).
- * `VTK_OPENGL_USE_GLES` (default `OFF`; forced `ON` for Android):
- Whether to use OpenGL ES API for OpenGL or not.
- * `VTK_OPENGL_HAS_EGL` (default `ON` for Android, `OFF` otherwise):
- Use to indicate that the OpenGL library being used supports EGL
- context management.
- * `VTK_DEFAULT_EGL_DEVICE_INDEX` (default `0`; requires
- `VTK_OPENGL_HAS_EGL`): The default EGL device to use for EGL render
- windows.
- * `VTK_DEFAULT_RENDER_WINDOW_OFFSCREEN` (default `OFF`): Whether to default
- to offscreen render windows by default or not.
- * `VTK_USE_OPENGL_DELAYED_LOAD` (default `OFF`; requires Windows and CMake >=
- 3.13): If set, use delayed loading to load the OpenGL DLL at runtime.
- * `VTK_DEFAULT_RENDER_WINDOW_HEADLESS` (default `OFF`; only available if
- applicable): Default to a headless render window.
- * `VTK_USE_WIN32_OPENGL` (default `ON` for Windows, forced `OFF` otherwise):
- Use Win32 APIs for render windows (typically only relevant for OSMesa on
- Windows builds).
-
-More advanced options:
-
- * `VTK_ABI_NAMESPACE_NAME` (default `<DEFAULT>` aka `""`): If set, VTK will
- wrap all VTK public symbols in an
- `inline namespace <VTK_ABI_NAMESPACE_NAME>` to allow runtime co-habitation
- with different VTK versions.
- * `VTK_BUILD_DOCUMENTATION` (default `OFF`): If set, VTK will build its API
- documentation using Doxygen.
- * `VTK_BUILD_SPHINX_DOCUMENTATION` (default `OFF`): If set, VTK will build its sphinx
- documentation website.
- * `VTK_BUILD_ALL_MODULES` (default `OFF`): If set, VTK will enable all
- modules not disabled by other features.
- * `VTK_ENABLE_REMOTE_MODULES` (default `ON`): If set, VTK will try to build
- remote modules (the `Remote` directory). If unset, no remote modules will
- build.
- * `VTK_ENABLE_EXTRA_BUILD_WARNINGS` (default `OFF`; requires CMake >= 3.19):
- If set, VTK will enable additional build warnings.
- * `VTK_ENABLE_EXTRA_BUILD_WARNINGS_EVERYTHING` (default `OFF`; requires
- `VTK_ENABLE_EXTRA_BUILD_WARNINGS` and `-Weverything` support): If set, VTK
- will enable all build warnings (with some explicitly turned off).
- * `VTK_USE_EXTERNAL` (default `OFF`): Whether to prefer external third
- party libraries or the versions VTK's source contains.
- * `VTK_TARGET_SPECIFIC_COMPONENTS` (default `OFF`): Whether to install
- files into target-specific components (`<TARGET>-runtime`,
- `<TARGET>-development`, etc.) or general components (`runtime`,
- `development`, etc.)
- * `VTK_VERSIONED_INSTALL` (default `ON`): Whether to add version numbers to
- VTK's include directories and library names in the install tree.
- * `VTK_CUSTOM_LIBRARY_SUFFIX` (default depends on `VTK_VERSIONED_INSTALL`):
- The custom suffix for libraries built by VTK. Defaults to either an empty
- string or `X.Y` where `X` and `Y` are VTK's major and minor version
- components, respectively.
- * `VTK_INSTALL_SDK` (default `ON`): If set, VTK will install its headers,
- CMake API, etc. into its install tree for use.
- * `VTK_FORBID_DOWNLOADS` (default `OFF`): If set, VTK will error on any
- network activity required during the build (namely remote modules and
- testing data).
- * `VTK_DATA_STORE` (default is complicated): If set or detected, points to
- where VTK external data will be stored or looked up.
- * `VTK_DATA_EXCLUDE_FROM_ALL` (default is complicated, but
- generally `OFF`): If set or detected, data downloads will only
- happen upon explicit request rather than through the build's
- default target.
- * `VTK_RELOCATABLE_INSTALL` (default `ON`): If set, the install tree will be
- relocatable to another path. If unset, the install tree may be tied to the
- build machine with absolute paths, but finding dependencies in
- non-standard locations may require work without passing extra information
- when consuming VTK.
- * `VTK_UNIFIED_INSTALL_TREE` (default `OFF`): If set, the install tree is
- stipulated to be a unified install tree of VTK and all of its dependencies;
- a unified tree usually simplifies things including, but not limited to,
- the Python module paths, library search paths, and plugin searching. This
- option is irrelevant if a relocatable install is requested as such setups
- assume that dependencies are set up either via a unified tree or some other
- mechanism such as modules).
- * `VTK_ENABLE_SANITIZER` (default `OFF`): Whether to enable sanitization of
- the VTK codebase or not.
- * `VTK_SANITIZER` (default `address`; requires `VTK_ENABLE_SANITIZER`): The
- sanitizer to use.
- * `VTK_USE_LARGE_DATA` (default `OFF`; requires `VTK_BUILD_TESTING`):
- Whether to enable tests which use "large" data or not (usually used to
- reduce the amount of data downloading required for the test suite).
- * `VTK_USE_HIP` (default `OFF`; requires CMAKE >= 3.21 and NOT `VTK_USE_CUDA`)
- Whether [HIP][hip] support will be available or not.
- * `VTK_LEGACY_REMOVE` (default `OFF`): If set, VTK will disable legacy,
- deprecated APIs.
- * `VTK_LEGACY_SILENT` (default `OFF`; requires `VTK_LEGACY_REMOVE` to be
- `OFF`): If set, usage of legacy, deprecated APIs will not cause warnings.
- * `VTK_USE_FUTURE_CONST` (default `OFF`): If set, the `VTK_FUTURE_CONST`
- macro expands to `const`; otherwise it expands to nothing. This is used to
- incrementally add more const correctness to the codebase while making it
- opt-in for backwards compatibility.
- * `VTK_USE_FUTURE_BOOL` (default `OFF`): If set, the `vtkTypeBool`
- typedef is defined to `bool`; otherwise it's `int`. VTK was created before
- C++ even had `bool`, and so its oldest code used `int`. Set to `ON` to opt in
- to using more real `bool`s, set to `OFF` only if required for backwards
- compatibility.
- * `VTK_USE_TK` (default `OFF`; requires `VTK_WRAP_PYTHON`): If set, VTK will
- enable Tkinter support for VTK widgets.
- * `VTK_BUILD_COMPILE_TOOLS_ONLY` (default `OFF`): If set, VTK will compile
- just its compile tools for use in a cross-compile build.
- * `VTK_SERIAL_TESTS_USE_MPIEXEC` (default `OFF`): Used on HPC to run
- serial tests on compute nodes. If set, it prefixes serial tests with
- "${MPIEXEC_EXECUTABLE}" "${MPIEXEC_NUMPROC_FLAG}" "1" ${MPIEXEC_PREFLAGS}
- * `VTK_WINDOWS_PYTHON_DEBUGGABLE` (default `OFF`): Set to `ON` if using a
- debug build of Python.
- * `VTK_WINDOWS_PYTHON_DEBUGGABLE_REPLACE_SUFFIX` (default `OFF`): Set to `ON`
- to use just a `_d` suffix for Python modules.
- * `VTK_BUILD_PYI_FILES` (default `OFF`): Set to `ON` to build `.pyi` type
- hint files for VTK's Python interfaces.
- * `VTK_DLL_PATHS` (default `""` or `VTK_DLL_PATHS` from the environment): If
- set, these paths will be added via Python 3.8's `os.add_dll_directory`
- mechanism in order to find dependent DLLs when loading VTK's Python
- modules. Note that when using the variable, paths are in CMake form (using
- `/`) and in the environment are a path list in the platform's preferred
- format.
- * `VTK_ENABLE_VR_COLLABORATION` (default `OFF`): If `ON`, includes support
- for multi client VR collaboration. Requires libzmq and cppzmq external libraries.
- * `VTK_SMP_ENABLE_<backend_name>` (default `OFF` if needs an external library otherwise `ON`):
- If set, builds with the specified SMPTools backend implementation that can be
- changed on runtime with `VTK_SMP_BACKEND_IN_USE` environment variable.
- * `VTK_USE_VIDEO_FOR_WINDOWS` (default `OFF`; requires Windows): Enable the
- `vtkAVIWriter` class in the `VTK::IOMovie` module.
- * `VTK_USE_VIDEO_FOR_WINDOWS_CAPTURE` (default `OFF`; requires Windows):
- Enable the `vtkWin32VideoSource` class in the `VTK::IOVideo` module.
- * `VTK_USE_MICROSOFT_MEDIA_FOUNDATION` (default `OFF`; requires Windows):
- Enable the `vtkMP4Writer` class in the `VTK::IOMovie` module.
- * `VTK_USE_64BIT_TIMESTAMPS` (default `OFF`; forced on for 64-bit builds):
- Build with 64-bit `vtkMTimeType`.
- * `VTK_USE_64BIT_IDS` (default `OFF` for 32-bit builds; `ON` for 64-bit
- builds): Whether `vtkIdType` should be 32-bit or 64-bit.
- * `VTK_DEBUG_LEAKS` (default `OFF`): Whether VTK will report leaked
- `vtkObject` instances at process destruction or not.
- * `VTK_DEBUG_RANGE_ITERATORS` (default `OFF`; requires a `Debug` build):
- Detect errors with `for-range` iterators in VTK (note that this is very
- slow).
- * `VTK_ALWAYS_OPTIMIZE_ARRAY_ITERATORS` (default `OFF`; requires `NOT
- VTK_DEBUG_RANGE_ITERATORS`): Optimize `for-range` array iterators even in
- `Debug` builds.
- * `VTK_ALL_NEW_OBJECT_FACTORY` (default `OFF`): If `ON`, classes using
- `vtkStandardNewMacro` will use `vtkObjectFactoryNewMacro` allowing
- overrides to be available even when not explicitly requested through
- `vtkObjectFactoryNewMacro` or `vtkAbstractObjectFactoryNewMacro`.
- * `VTK_ENABLE_VTKM_OVERRIDES` (default `OFF`): If `ON`, enables factory override
- of certain VTK filters by their VTK-m counterparts. There is also a runtime
- switch that can be used to enable/disable the overrides at run-time (on by default).
- It can be accessed using the static function `vtkmFilterOverrides::SetEnabled(bool)`.
- * `VTK_GENERATE_SPDX` (default `OFF`): If `ON`, SPDX file will be generated at build time
- and installed for each module and third party, in order to be able to create a SBOM.
- See [](/api/cmake/ModuleSystem.md#spdx-files-generation) and
- [](/advanced/spdx_and_sbom.md) for more info.
-
-`vtkArrayDispatch` related options:
-
-The `VTK_DISPATCH_<array_type>_ARRAYS` options (default `OFF` for all but AOS) enable the
-specified type of array to be included in a dispatch type list. Explicit arrays (such as
-AOS, SOA and Typed) are included in the `vtkArrayDispatchTypeList.h` while
-`vtkArrayDispatchImplicitTypeList.h` includes both explicit and implicit arrays. The implicit
-array framework is included in the `CommonImplicitArrays` module. The following array types
-currently exist for use with the VTK dispatch mechanism:
-
- * `VTK_DISPATCH_AOS_ARRAYS` (default `ON`): includes dispatching for the commonly used
- "array-of-structure" ordered arrays derived from `vtkAOSDataArrayTemplate`
- * `VTK_DISPATCH_SOA_ARRAYS` (default `OFF`): includes dispatching for "structure-of-array"
- ordered arrays derived from `vtkSOADataArrayTemplate`
- * `VTK_DISPATCH_TYPED_ARRAYS` (default `OFF`): includes dispatching for arrays derived
- from `vtkTypedDataArray`
- * `VTK_DISPATCH_AFFINE_ARRAYS` (default `OFF`): includes dispatching for linearly varying
- `vtkAffineArray`s as part of the implicit array framework
- * `VTK_DISPATCH_CONSTANT_ARRAYS` (default `OFF`): includes dispatching for constant arrays
- `vtkConstantArray` as part of the implicit array framework
- * `VTK_DISPATCH_STD_FUNCTION_ARRAYS` (default `OFF`): includes dispatching for arrays with
- an `std::function` backend `vtkStdFunctionArray` as part of the implicit array framework
- * `VTK_DISPATCH_COMPOSITE_ARRAYS` (default `OFF`): includes dispatching of arrays with a
- `vtkCompositeImplicitBackend` backend, `vtkCompositeArray`, as part of the implicit array
- framework
- * `VTK_DISPATCH_INDEXED_ARRAYS` (default `OFF`): includes dispatching of arrays with a
- `vtkIndexedImplicitBackend` backend, `vtkIndexedArray`, as part of the implicit array
- framework
-
-The outlier in terms of dispatch support is the family of arrays derived from
-`vtkScaledSOADataArrayTemplate` which are automatically included in dispatch when built setting
-the `VTK_BUILD_SCALED_SOA_ARRAYS`.
-
-```{warning}
-Adding increasing numbers of arrays in the dispatch mechanism can greatly slow down compile times.
-```
-
-The VTK module system provides a number of variables to control modules which
-are not otherwise controlled by the other options provided.
-
- * `VTK_MODULE_USE_EXTERNAL_<name>` (default depends on `VTK_USE_EXTERNAL`):
- Use an external source for the named third-party module rather than the
- copy contained within the VTK source tree.
-
- ````{warning}
- Activating this option within an interactive cmake configuration (i.e. ccmake, cmake-gui)
- could end up finding libraries in the standard locations rather than copies
- in non-standard locations.
-
- It is recommended to pass the variables necessary to find the intended external package to
- the first configure to avoid finding unintended copies of the external package.
- The variables which matter depend on the package being found, but those ending with
- `_LIBRARY` and `_INCLUDE_DIR` as well as the general CMake `find_package` variables ending
- with `_DIR` and `_ROOT` are likely candidates.
-
- Example:
- ```
- ccmake -D HDF5_ROOT:PATH=/home/user/myhdf5 ../vtk/sources
- ```
- ````
-
- * `VTK_MODULE_ENABLE_<name>` (default `DEFAULT`): Change the build settings
- for the named module. Valid values are those for the module system's build
- settings (see below).
- * `VTK_GROUP_ENABLE_<name>` (default `DEFAULT`): Change the default build
- settings for modules belonging to the named group. Valid values are those
- for the module system's build settings (see below).
-
-For variables which use the module system's build settings, the valid values are as follows:
-
- * `YES`: Require the module to be built.
- * `WANT`: Build the module if possible.
- * `DEFAULT`: Use the settings by the module's groups and
- `VTK_BUILD_ALL_MODULES`.
- * `DONT_WANT`: Don't build the module unless required as a dependency.
- * `NO`: Do not build the module.
-
-If any `YES` module requires a `NO` module, an error is raised.
-
-[cuda]: https://developer.nvidia.com/cuda-zone
-[hip]: https://en.wikipedia.org/wiki/ROCm
-[mpi]: https://www.mcs.anl.gov/research/projects/mpi
diff --git a/Documentation/dev/git/README.md b/Documentation/dev/git/README.md
deleted file mode 100644
index 0dfcb86a3a445a71707899dbb941d8ec26e055f3..0000000000000000000000000000000000000000
--- a/Documentation/dev/git/README.md
+++ /dev/null
@@ -1,37 +0,0 @@
-VTK Git Usage
-=============
-
-VTK version tracking and development is hosted by [Git](http://git-scm.com).
-Please select a task for further instructions:
-
-Main Tasks
-----------
-* [Install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- Git 1.7.2 or greater is preferred (required for development)
-
-* [Download VTK](download.md) - Users start here
-
-* [Develop VTK](develop.md) - Contributors start here
-
-Other Tasks
------------
-
-* [Review Changes](https://gitlab.kitware.com/vtk/vtk/-/merge_requests) -
- VTK GitLab Merge Requests
-
-* [Test VTK](dashboard.md) - CDash client setup
-
-* [Learn Git](http://public.kitware.com/Wiki/Git/Resources) -
- Third-party documentation
-
-Branches
---------
-
-The upstream VTK repository has the following branches:
-
-* `master`: Development (default)
-* `release`: Maintenance of latest release
-* `nightly-master`: Follows `master`, updated at `01:00 UTC`
-* `hooks`: Local commit hooks
- ([placed](http://public.kitware.com/Wiki/Git/Hooks#Local) in `.git/hooks`)
-* `dashboard`: Dashboard script ([setup](dashboard.md) a CDash client)
diff --git a/Documentation/dev/git/dashboard.md b/Documentation/dev/git/dashboard.md
deleted file mode 100644
index 796c45c10e63db5472cfd0afd6cf3f8b4a083053..0000000000000000000000000000000000000000
--- a/Documentation/dev/git/dashboard.md
+++ /dev/null
@@ -1,48 +0,0 @@
-Dashboard Scripts
-=================
-
-This page documents how to use the VTK `dashboard` branch in [Git][].
-See the [README](README.md) for more information.
-
-[Git]: http://git-scm.com
-
-Using the Dashboard Scripts
----------------------------
-
-The `dashboard` branch contains a dashboard client helper script.
-Use these commands to track it:
-
- $ mkdir -p ~/Dashboards/VTKScripts
- $ cd ~/Dashboards/VTKScripts
- $ git init
- $ git remote add -t dashboard origin https://gitlab.kitware.com/vtk/vtk.git
- $ git pull origin
-
-The `vtk_common.cmake` script contains setup instructions in its
-top comments.
-
-Update the `dashboard` branch to get the latest version of this
-script by simply running:
-
- $ git pull
-
-Here is a link to the script as it appears today: [vtk_common.cmake][].
-
-[vtk_common.cmake]: https://gitlab.kitware.com/vtk/vtk/-/tree/dashboard/vtk_common.cmake
-
-Changing the Dashboard Scripts
-------------------------------
-
-If you find bugs in the hooks themselves or would like to add new features,
-the can be edited in the usual Git manner:
-
- $ git checkout -b my-topic-branch
-
-Make your edits, test it, and commit the result. Create a patch file with:
-
- $ git format-patch origin/dashboard
-
-And post the results in the [Development][] category in the [VTK Discourse][] forum.
-
-[Development]: https://discourse.vtk.org/c/development
-[VTK Discourse]: https://discourse.vtk.org/
diff --git a/Documentation/dev/git/deprecation.md b/Documentation/dev/git/deprecation.md
deleted file mode 100644
index 7b95657676099982139400fd7c302d01882f4b68..0000000000000000000000000000000000000000
--- a/Documentation/dev/git/deprecation.md
+++ /dev/null
@@ -1,77 +0,0 @@
-Deprecation Process
-===================
-
-This page documents how to deprecate an API and mark it as no longer necessary
-for downstream consumers of VTK.
-
-Deprecating classes and methods
--------------------------------
-
-Classes, functions, and methods may be deprecated using the deprecation macros.
-
-```c++
-#include "vtkDeprecation.h" // Include the macros.
-
-// A deprecated class.
-VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation")
-class oldClass {
-public:
- // A deprecated method.
- VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation")
- void oldMethod();
-};
-
-// A deprecated function.
-VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation")
-void oldFunction();
-```
-
-The `X_Y_Z` should be the newest macro available in the `vtkDeprecation.h`
-header when the API is added.
-
-Note that, unlike, the old `VTK_LEGACY_REMOVE` mechanism, the APIs are not
-deleted. This does interfere with various kinds of deprecations.
-
- - *Changing the return type*: Don't do this. Use a new name for the
- function/method.
- - *Deprecating macros*: Use `VTK_LEGACY_REMOVE`. New macro APIs should be
- highly discouraged.
-
-### Lifetime of deprecated APIs
-
-Deprecated APIs should exist for at least one release with the deprecation
-warning active. This gives consumers of VTK at least one cycle to notice the
-deprecation and move off of it.
-
-Upon branching for a release, `master` will soon after have all instances of
-deprecated symbols removed.
-
-### Avoiding warnings within VTK
-
-VTK is providing the deprecated symbols and as such may still use them in tests
-or implementations. Since these generate warnings when compiling VTK itself,
-classes which define deprecated symbols must suppress them.
-
-Sources which continue to use the deprecated macros should add a comment to the
-top of the source file to hide deprecation warnings in CI.
-
-```c++
-// Hide VTK_DEPRECATED_IN_X_Y_Z() warnings for this class.
-#define VTK_DEPRECATION_LEVEL 0
-```
-
-If one already exists, please add another comment to it so that when deprecated
-symbols are removed, it shows up in the search.
-
-Using `VTK_DEPRECATION_LEVEL`
------------------------------
-
-When using VTK, the `VTK_DEPRECATION_LEVEL` macro may be set to a version
-number. APIs which have been deprecated after this point will not fire (as the
-API is not deprecated as of the level requested). It should be defined using
-the `VTK_VERSION_CHECK(major, minor, patch)` macro.
-
-Note that APIs on the verge of deletion (those deprecated in at least one
-release) will always raise deprecation warnings.
-
-If not set, its value defaults to the current level of VTK.
diff --git a/Documentation/dev/git/develop_quickstart.md b/Documentation/dev/git/develop_quickstart.md
deleted file mode 100644
index c2d8c3527410e03406fa210267e2081e4c1743ae..0000000000000000000000000000000000000000
--- a/Documentation/dev/git/develop_quickstart.md
+++ /dev/null
@@ -1,197 +0,0 @@
-# Quick Start Guide
-
-This is a quick start guide so that you can start contributing to VTK easily.
-To understand the process more deeply, you can jump to the [workflow](develop.md#workflow)
-section.
-
-## Initial Setup
-
-Before you begin, perform your initial setup using the following steps:
-
-1. Register [GitLab Access] to create an account and select a user name.
-
-2. [Fork VTK][] into your user's namespace on GitLab.
-
-3. Follow the [download instructions](download.md#clone) to create a
- local clone of the main VTK repository:
-
- $ git clone --recursive https://gitlab.kitware.com/vtk/vtk.git VTK
-
- The main repository will be configured as your `origin` remote.
-
-4. Run the [developer setup script][] to prepare your VTK work tree and
- create Git command aliases used below:
-
- $ ./Utilities/SetupForDevelopment.sh
-
- This will prompt you for your GitLab username and configure a remote
- called `gitlab` to refer to your fork. It will also setup a data directory for you.
- No need to do anything else.
-
-[GitLab Access]: https://gitlab.kitware.com/users/sign_in
-[Fork VTK]: https://gitlab.kitware.com/vtk/vtk/-/forks/new
-[developer setup script]: /Utilities/SetupForDevelopment.sh
-
-## Development
-
-Create a local branch for your changes:
-
-```
-git checkout -b your_branch
-```
-
-Make the needed changes in VTK and use git locally to create logically separated commits.
-There is no strict requirements regarding git commit messages syntax but a good rule of
-thumb to follow is: `General domain: reason for change`, General domain being a class, a module
-, a specific system like build or CI.
-
-```
-git commit -m "General domain: Short yet informative reason for the change"
-```
-
-Build VTK following the [guide][] and fix any build warnings or issues that arise and seems related to your changes.
-
-[guide]: /Documentation/dev/build.md
-Add/Improve tests in order to ensure your changes are tested. Take a look in the `Testing` directory
-of the module you are making changes in to see how the tests are currently built and try to follow the same paradigms.
-Run your test locally from your build directory and check that they pass:
-
-```
-cmake . && cmake --build .
-ctest -VV -R yourTest
-```
-
-## Upload
-
-Push your changes to the GitLab fork that you created in the [initial setup](#initial-setup) stage:
-
-```
-git push gitlab
-```
-
-## Data
-
-If your test uses new data or baselines, you will need to add it to your fork.
-For data, add the file names to the list in your module `yourModule/Testing/CMakeLists.txt` and drop the files in `Testing/Data/`.
-For baselines, just drop the file in `yourModule/Testing/Data/Baselines` and run the following commands from your build directory:
-
-```
-cmake . && cmake --build .
-```
-
-This will transform your files into .sha512 files. Check your test is passing by running from your build directory:
-
-```
-ctest -VV -R yourTest
-```
-
-If it passes, add these .sha512 files and commit them, then push with:
-
-```
-git gitlab-push
-```
-
-## Create a Merge Request
-
-Once you are happy with the state of your development on your fork, the next step is to create a merge request back into the main VTK repository.
-
-Open [](https://gitlab.kitware.com/username/vtk/-/merge_requests/new) in a browser, select your branch in the list and create a Merge Request against master.
-
-In the description, write an informative explanation of your added features or bugfix. If there is an associated issue, link it with the `#number` in the description.
-
-Tag some VTK maintainers in the description to ensure someone will see it, see here for the complete [list](develop.md#review-a-merge-request).
-
-## Robot Checks
-
-Once the MR is created, our GitLab robot will check multiple things and make automated suggestions. Please read them and try to follow the instructions.
-The two standard suggestions are related to formatting errors and adding markdown changelog.
-
-To fix the formatting, just add a comment containing:
-
-```
-Do: reformat
-```
-
-Then, once the robot has fixed the formatting, fetch the changes locally (this will remove any local changes to your branch)
-
-```
-git fetch gitlab
-git reset --hard gitlab/your_branch
-```
-
-To fix the changelog warning, create, add, commit and push a markdown (.md) file in `Documentation/release/dev` folder.
-In this file, write a small markdown paragraph describing the development.
-See other .md files in this folder for examples. It may look like this:
-
-```
-## Development title
-
-A new feature that does this and that has been introduced.
-This specific issue has been fixed in this particular way.
-```
-
-Suggestions and best practices on writing the changelog can be found in the `Documentation/release/dev/0-sample-topic.md` file.
-This is an optional step but recommended to do for any new feature and user facing issues.
-
-## Reviews
-
-VTK maintainers and developers will review your MR by leaving comments on it. Try to follow their instructions and be patient.
-It can take a while to get a MR into mergeable form. This is a mandatory step, and it is absolutely normal to get change requests.
-
-Review comments can be resolved, please resolve a comment once you've taken it into account and pushed related changes
-or once you've reached an agreement with the commenter that nothing should be changed.
-
-Once a reviewer is happy with your changes, they will add a `+X` comment. You need at least one `+2` or higher to consider
-merging the MR. Two `+1`s do not equal a `+2`. If a reviewer leave a `-1` comment, please discuss with them to understand what is the issue and how it could be fixed.
-
-Once you have pushed new changes, please tag reviewers again so that they can take a look.
-If you do not tag reviewers, they may not know to revisit your changes. _Do not hesitate to tag them and ask for help_.
-
-## Continuous Integration
-
-Before merging a MR, the VTK continuous integration (CI) needs to run and be green.
-For CI to be functional, please read and follow this [guide](https://discourse.vtk.org/t/the-ultimate-how-to-make-ci-work-with-my-fork-guide/7581).
-
-To run the CI:
- - Click on the Pipelines Tab
- - Click on the last pipeline status badge
- - Press the `Play all manual` arrows on top of the Build and Test stages
-
-Do not hesitate to tag a VTK developer for help if needed.
-
-You then need to wait for CI to run, it can take a while, up to a full day.
-
-A successful CI should be fully green. If that is so, then your MR is ready !
-
-If not, you need to analyse the issues and fix them. Recover the failure information this way:
-
-Click on the pipelines tab, then on the last status badge, then on the `cdash-commit` job.
-It will take you to the related CDash report where you will find all information.
-
-Everything in the CDash report should be green except the `NotRun` and `Time` column. Take a look into each issue and fix them locally.
-If there are issues in the pipeline but nothing is visible in the CDash, please ask a maintainer for help to figure out if anything should be done.
-You can always try to rerun the failed job by clicking on the arrow of the job in the pipeline.
-
-Once you have fixed some issues locally, commit and push them to gitlab, run the CI again and tag reviewers again for follow-up reviews.
-
-## Merging
-
-Once the MR has green CI and you have at least one `+2`, you can ask for a merge. Before that please make sure that:
- - Your commit history is logical (or squashed into a single commit) and cleaned up with good commit messages
- - You are rebased on a fairly recent version of master
-
-If that is not the case, please rebase on master using the following commands:
-
-```
-git fetch origin
-git rebase -i origin/master
-git push gitlab -f
-```
-
-The interactive rebase will let you squash commits, reorganize commits and edit commit messages.
-
-After the force push, make sure to run CI again.
-
-Once all is done, tag a VTK developer so that they can perform the merge command.
-
-__Congratulations ! You just contributed to VTK !__
diff --git a/Documentation/dev/git/download.md b/Documentation/dev/git/download.md
deleted file mode 100644
index 6d6616bb43b0b4186d6f26a3cac10854688e0d02..0000000000000000000000000000000000000000
--- a/Documentation/dev/git/download.md
+++ /dev/null
@@ -1,51 +0,0 @@
-Download VTK with Git
-=====================
-
-This page documents how to download VTK source code through [Git][].
-See the [README](README.md) for more information.
-
-[Git]: http://git-scm.com
-
-Clone
------
-
-Clone VTK using the commands:
-
- $ git clone https://gitlab.kitware.com/vtk/vtk.git VTK
- $ cd VTK
- $ git submodule update --init
-
-Update
-------
-
-Users that have made no local changes and simply want to update a
-clone with the latest changes may run:
-
- $ git pull
-
-Avoid making local changes unless you have read our [developer instructions][].
-
-[developer instructions]: develop.md
-
-Release
--------
-
-After cloning your local repository will be configured to follow the upstream
-`master` branch by default. One may create a local branch to track the
-upstream `release` branch instead, which should guarantee only bug fixes to
-the functionality available in the latest release:
-
- $ git checkout --track -b release origin/release
-
-This local branch will always follow the latest release.
-Use the [above instructions](#update) to update it.
-Alternatively one may checkout a specific release tag:
-
- $ git checkout v6.2.0
-
-Release tags never move. Repeat the command with a different tag to get a
-different release. One may list available tags:
-
- $ git tag
-
-and then checkout any tag listed.
diff --git a/Documentation/dev/release_process.md b/Documentation/dev/release_process.md
deleted file mode 100644
index 3ca63e73590960f241b7e7d8a6c3276c716b4fb1..0000000000000000000000000000000000000000
--- a/Documentation/dev/release_process.md
+++ /dev/null
@@ -1,171 +0,0 @@
-# Release Process
-
-This document provides a high-level overview of the VTK release cycle and
-associated release process.
-
-## Overview
-
-We aim to release a new version of VTK every six months. However, we recognize
-that this schedule is flexible. The project is funded and developed by many
-different groups, each of which works towards their own particular sets of
-features.
-
-VTK releases are named with a `Major.Minor.Patch` scheme.
-
-## Branching Scheme
-
-The overall release history resembles a skinny tree. Development proceeds along
-the `master` branch, consisting of topic branches that start from and are merged
-into `master`. Every so often, a release is tagged and branched from it.
-
-In general, no work takes place on the `release` branch, other than the handful
-of important patches that make up occasional patch releases.
-
-:::{hint}
-Steps for contributing changes specific to the `release` branch are documented in
-[](git/develop.md#create-a-topic).
-:::
-
-On the `master` branch, bug fixes and new features are continuously
-developed. At release time, the focus temporarily shifts to producing
-a library that is as stable and robust as possible.
-
-## Steps
-
-The process for cutting releases is as follows:
-
-1. Announce upcoming release
-
- A few weeks before the intended `release` branch, announce on [VTK Discourse](https://discourse.vtk.org/)
- that a new release is coming. This alerts developers to avoid making drastic
- changes that might delay the release and gives them a chance to push important
- and nearly completed features in time for the release. For example,
- see [this post](https://discourse.vtk.org/t/vtk-9-2-0-release-cycle/8149).
-
-2. Polish the dashboards and bug tracker by addressing outstanding issue and
- coordinate effort with relevant developers.
-
- Persistent compilation and regression test problems are fixed. Serious
- outstanding bugs are fixed.
-
-3. [Create a new issue](https://gitlab.kitware.com/vtk/vtk/-/issues/new) titled
- `Release X.Y.Z[rcN]` based of the [new-release](https://gitlab.kitware.com/vtk/vtk/-/blob/master/.gitlab/issue_templates/new-release.md?plain=1) template.
-
- :::{Important}
- Specific steps to create eiter the candidate or the official release are found
- in the newly created issue.
- :::
-
-4. Perform the release candidate cycle
-
- 1. Tag the release branch and create and publish release candidate
- artifacts and change summaries.
-
- 2. Announce the release candidate and request feedback from the
- community, especially third-party packagers.
-
- :::{hint}
- Bug reports should be entered into the bug tracker with the upcoming
- release number as the milestone.
- :::
-
- 3. If the community reports bugs, classify them in the bug tracker and ensure
- they are fixed.
-
- Only serious bugs and regressions need to be fixed before the release.
- New features and minor problems should be merged into `master` as usual.
-
- Patches for the release branch should start from the release branch, be
- submitted through GitLab, and then merged into `master`. Once fully
- tested there, the branch can be merged into the release branch.
-
- When the selected issues are fixed in the release branch, tag the tip
- of the release branch and release it as the next candidate, then the
- cycle continues.
-
- 4. Distribution specific patches can accumulate over time. Consider reviewing the
- following distribution specific pages to identify potential fixes and improvements
- that could be integrated in VTK itself:
-
- * Debian:
- - https://tracker.debian.org/pkg/vtk9
- - https://udd.debian.org/patches.cgi?src=vtk9
-
- * Gentoo:
- - https://packages.gentoo.org/packages/sci-libs/vtk
- - https://gitweb.gentoo.org/repo/gentoo.git/tree/sci-libs/vtk/files
-
- * openSUSE:
- - https://build.opensuse.org/package/show/openSUSE:Factory/vtk
-
-5. Package the official release
-
- The official VTK package consists of tar balls and ZIP files of the source,
- Python Wheels, Doxygen documentation, and regression test data, all at the
- tag point.
-
- Volunteer third-party packagers create binary packages from the official
- release for various platforms, so their input is especially valuable during
- the release cycle.
-
- The release manager also compiles release notes for the official release
- announcement. Release notes are compiled from various [standardized topic documents](https://gitlab.kitware.com/vtk/vtk/-/tree/master/Documentation/release)
- added to the `Documentation/release/dev` folder while features or issues
- are fixed. The aggregation of these topic files is done manually and
- results in the creation of a file named `Documentation/release/X.Y.md` for
- the current release.
-
-## GitLab and Releases
-
-GitLab milestones are used for keeping track of branches for the release. They
-allow keeping track of issues and merge requests which should be "done" for
-the milestone to be considered complete.
-
-For each release (including release candidates), a milestone is created with a
-plausible due date. The milestone page allows for an easy overview of branches
-which need wrangling for a release.
-
-### Merge Requests
-
-Merge requests which need to be rebased onto the relevant release branch
-should be marked with the `needs-rebase-for-release` tag and commented on how
-the branch can be rebased properly:
-
- This branch is marked for a release, but includes other commits in
- `master`. Please either rebase the branch on top of the release branch and
- remove the `needs-rebase-for-release` tag from the merge request:
-
- ```sh
- $ git rebase --onto=origin/release origin/master $branch_name
- $ git gitlab-push -f
- ```
-
- or, if there are conflicts when using a single branch, open a new branch
- and open a merge request against the `release` branch:
-
- ```sh
- $ git checkout -b ${branch_name}-release $branch_name
- $ git rebase --onto=origin/release origin/master ${branch_name}-release
- $ git gitlab-push
- ```
-
- Thanks!
-
-### Wrangling Branches
-
-Branches may be wrangled using the filters in the merge request page. Replace
-`$release` at the end with the relevant milestone name:
-
- https://gitlab.kitware.com/vtk/vtk/-/merge_requests?state=all&milestone_title=$release
-
-The following states of a merge request indicate where they are in the flow:
-
- - open for `master`: get into `master` first
- - open for `release`: ensure it is already in `master`
- - open with `needs-rebase-for-release` tag: wait for contributor to rebase
- properly; ping if necessary
- - `MERGED`: merge into `release`
-
-There is currently no good way of marking a branch that went towards `master`
-is also in `release` already since tags cannot be added to closed merge
-requests. Suggestions welcome :) .
diff --git a/Documentation/dev/testing.md b/Documentation/dev/testing.md
deleted file mode 100644
index 34d16abce356511fbdf3a84de7a41ad1c2a8ce2d..0000000000000000000000000000000000000000
--- a/Documentation/dev/testing.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Regression Testing
-
-## Testing and dashboard submitter setup
-
-Regression testing in VTK takes the form of a set of programs, that are included in the VTK source code and enabled in builds configured through CMake to have the `VTK_BUILD_TESTING` flag turned on. Test pass/fail results are returned to CTest via a test program's exit code. VTK contains helper classes that do specific checks, such as comparing a produced image against a known valid one, that are used in many of the regression tests. Test results may be submitted to Kitware's CDash instance, were they will be gathered and displayed at <http://open.cdash.org/index.php?project=VTK>
-
-All proposed changes to VTK are automatically tested on Windows, Mac and Linux machines. All changes that are merged into the master branch are subsequently tested again by more rigorously configured Windows, Mac and Linux continuous dashboard submitters. After 9PM Eastern Time, the master branch is again tested by a wider set of machines and platforms. These results appear in the next day's page.
-
-At each step in the code integration path the developers who contribute and merge code are responsible for checking the test results to look for problems that the new code might have introduced. Plus signs in CDash indicate newly detected problems. Developers can correlate problems with contributions by logging in to CDash. Submissions that contain a logged in developer's change are highlighted with yellow dots.
-
-It is highly recommended that developers test changes locally before submitting them. To run tests locally:
-
-1. Configure with `VTK_BUILD_TESTING` set ON
-
- The exact set of tests created depends on many configuration options. Tests in non-default modules are only tested when those modules are purposefully enabled, the smoke tests described in the Coding Style section above are enabled only when the python or Tcl interpreter is installed, tests written in wrapped languages are only enabled when wrapping is turned on, etc.
-
-1. Build.Â
-
- VTK tests are only available from the build tree.
-
-1. Run ctest at the command line in the build directory or make the TESTING target in Visual Studio.
-
- As ctest runs the tests it prints a summary. You should expect 90% of the tests or better to pass if your VTK is configured correctly. Detailed results (which are also printed if you supply a --V argument to ctest) are put into the Testing/Temporary directory. The detailed results include the command line that ctest uses to spawn each test. Other particularly useful arguments are:
- ```bash
- --R TestNameSubstringToInclude to choose tests by name
-
- --E TestNameSubstringToExclude to reject tests by name
-
- --I start,stop,step to run a portion of the tests
-
- --j N to run N tests simultaneously.
- ```
-
-Dashboard submitting machines work at a slightly higher level of abstraction that adds the additional stages of downloading, configuring and building VTK before running the tests, and submitting all results to CDash afterward. With a build tree in place you can run "ctest --D Experimental" to run at this level and submit the results to the experimental section of the VTK dashboard or "ctest --M Experimental -T Build --T Submit" etc to pick and choose from among the stages. When setting up a test submitter machine one should start with the experimental configuration and then, once the kinks are worked out, promote the submitter to the Nightly section.
-
-The volunteer machines use cron or Windows task scheduler to run CMake scripts that configure a VTK build with specific options, and then run ctest --D as above. Within CDash, you can see each test machine's specific configuration by clicking on the Advanced View and then clicking on the note icon in the Build Name column. This is a useful starting point when setting up a new submitter. It is important that each submitter's dashboard script include the name of the person who configures or maintains the machine so that, when the machine has problems, the dashboard maintainer can address it.
-
-For details about the Continuous Integration infrastructure hosted at Kitware see [here](git/develop.md#continuous-integration).
diff --git a/Documentation/docs/advanced/.gitignore b/Documentation/docs/advanced/.gitignore
deleted file mode 100644
index b55f30f87ab43864292960cfe86094981b60db88..0000000000000000000000000000000000000000
--- a/Documentation/docs/advanced/.gitignore
+++ /dev/null
@@ -1,5 +0,0 @@
-# generated by conf.py
-build_for_mobile.md
-build_python_wheels.md
-build_wasm_emscripten.md
-build_documentation.md
diff --git a/Documentation/docs/advanced/PythonWrappers.md b/Documentation/docs/advanced/PythonWrappers.md
index e11888d106b11a6ed5d92d9b8e52f4f344e4a6e0..477e919c3716772495a376975c1c85c2b6e536c3 100644
--- a/Documentation/docs/advanced/PythonWrappers.md
+++ b/Documentation/docs/advanced/PythonWrappers.md
@@ -1,2 +1,1156 @@
-```{include} ../../Doxygen/PythonWrappers.md
+# Python Wrappers
+
+## Introduction
+
+This document is a reference for using VTK from Python. It is not a tutorial
+and provides very little information about VTK itself, but instead describes
+in detail the features of the Python wrappers and how using VTK from Python
+differs from using VTK from C++. It assumes that the reader is already
+somewhat familiar with both Python and VTK.
+
+
+## Background
+
+The Python wrappers are automatically generated from the VTK source code,
+and for the most part, there is a one-to-one mapping between the VTK classes
+and methods that you can use from Python and the ones that you can use from
+C++. More specifically, the wrappers are a package of Python extension modules
+that interface directly to the VTK C++ libraries. When you use VTK through
+the wrappers, you are actually executing compiled C++ code, and there is
+very little performance difference between VTK/C++ and VTK/Python.
+
+
+## Installation
+
+VTK for Python can be installed via either conda or pip, where the conda
+packages is maintained on conda-forge, while the pip packages are maintained
+by the VTK developers themselves. If you are first getting started, then pip
+is probably the most convenient way to install VTK for Python:
+
+ pip install vtk
+
+This will provide a basic installation of VTK that includes all core
+functionality, but which will not include some of the specialized VTK
+modules that rely on external libraries. Binary packages for VTK can
+also be downloaded directly from https://www.vtk.org/download/.
+
+Instructions for building VTK from source code are given in the file
+[Documentation/dev/build.md][vtk-build] within the source repository.
+
+[vtk-build]: https://gitlab.kitware.com/vtk/vtk/-/blob/release/Documentation/dev/build.md
+
+
+## Importing
+
+VTK is comprised of over one hundred individual modules. Programs can import
+just the modules that are needed, in order to reduce load time.
+
+ from vtkmodules.vtkCommonCore import vtkObject
+ from vtkmodules.vtkFiltersSources import vtkConeSource, vtkSphereSource
+ from vtkmodules.vtkRenderingCore import (
+ vtkActor,
+ vtkDataSetMapper,
+ vtkRenderer,
+ vtkRenderWindow
+ )
+ import vtkmodules.vtkRenderingOpenGL2
+
+When getting started, however, it is hard to know what modules you will need.
+So if you are experimenting with VTK in a Python console, or writing a quick
+and dirty Python script, it is easiest to simply import everything. There
+is a special module called '`all`' that allows this to be done:
+
+ from vtkmodules.all import *
+
+After importing the VTK classes, you can check to see which module each of the
+classes comes from:
+
+ for c in vtkObject, vtkConeSource, vtkRenderWindow:
+ print(f"from {c.__module__} import {c.__name__}")
+
+The output is as follows:
+
+ from vtkmodules.vtkCommonCore import vtkObject
+ from vtkmodules.vtkFiltersSources import vtkConeSource
+ from vtkmodules.vtkRenderingCore import vtkRenderWindow
+
+### Factories and Implementation Modules
+
+In the first 'import' example above, you might be wondering about this line:
+
+ import vtkmodules.vtkRenderingOpenGL2
+
+This import is needed because `vtkRenderingOpenGL2` provides the OpenGL
+implementations of the classes in `vtkRenderingCore`. To see this in action,
+open a new Python console and do the following:
+
+ >>> from vtkmodules.vtkRenderingCore import vtkRenderWindow
+ >>> renwin = vtkRenderWindow()
+ >>> type(renwin)
+ <class 'vtkmodules.vtkRenderingCore.vtkRenderWindow'>
+ >>>
+ >>> import vtkmodules.vtkRenderingOpenGL2
+ >>> renwin2 = vtkRenderWindow()
+ >>> type(renwin2)
+ <class 'vtkmodules.vtkRenderingOpenGL2.vtkXOpenGLRenderWindow'>
+
+After `vtkRenderingOpenGL2` has been imported, the `vtkRenderWindow()`
+constructor magically starts returning a different type of object.
+This occurs because `vtkRenderWindow` is a *factory* class, which means that
+the kind of object it produces can be overridden by an *implementation*
+class. In order for the implementation class to do the override, all that
+is necessary is that its module is imported. To make things even more
+confusing, `vtkRenderingOpenGL2` is not the only module that contains
+implementations for the factory classes in `vtkRenderingCore`. The following
+modules are often needed, as well:
+
+ import vtkmodules.vtkInteractionStyle
+ import vtkmodules.vtkRenderingFreeType
+
+Although you only need implementations for the factory classes that you use,
+it can be hard to know which classes are factory classes, or what modules
+contain implementations for them. Also, it can be difficult to even know
+what classes you are using, since many VTK classes make use of other VTK
+classes. An example of this is `vtkDataSetMapper`, which internally uses
+`vtkPolyDataMapper` to do the rendering. So even though `vtkDataSetMapper` is
+not a factory class, it needs an OpenGL implementation for `vtkPolyDataMapper`.
+
+The simplest approach is to import all the important implementation modules
+into your program, even if you are not certain that you need them.
+* For `vtkRenderingCore`, `import vtkRenderingOpenGL2, vtkRenderingFreeType, vtkInteractionStyle`
+* For `vtkRenderingVolume`, `import vtkRenderingVolumeOpenGL2`
+* For `vtkCharts`, `import vtkContextOpenGL2`
+
+### Classic VTK Import
+
+There are many VTK programs that still import the '`vtk`' module, which
+has been available since VTK 4.0, rather than using the '`vtkmodules`'
+package that was introduced in VTK 8.2:
+
+ import vtk
+
+The advantage (and disadvantage) of this is that it imports everything. It
+requires just one import statement for all of VTK, but it can be slow because
+VTK has grown to be very large over the years.
+
+Also note that, between VTK 8.2 and VTK 9.2.5, the use of the `vtk` module
+would confuse the auto-completion features of IDEs such as PyCharm. This
+was fixed in VTK 9.2.6. For 9.2.5 and earlier, the following can be used:
+
+ import vtkmodules.all as vtk
+
+From the programmer's perspective, this is equivalent to '`import vtk`'.
+
+## VTK Classes and Objects
+
+### Classes Derived from vtkObjectBase
+
+In C++, classes derived from `vtkObjectBase` are instantiated by calling
+`New()`. In Python, these classes are instantiated by simply calling the
+constructor:
+
+ o = vtkObject()
+
+For factory classes, the returned object's type might be a subtype of the
+class. This occurs because the Python wrappers are actually calling `New()`
+for you, which allows the VTK factory overrides to occur:
+
+ >>> a = vtkActor()
+ >>> type(a)
+ <class 'vtkmodules.vtkRenderingOpenGL2.vtkOpenGLActor'>
+
+When you create a VTK object in Python, you are in fact creating two
+objects: a C++ object, and a Python object that holds a pointer to the C++
+object. The `repr()` of the object shows the memory address of the C++
+object (in parentheses) and of the Python object (after the '`at`'):
+
+ >>> a = vtkFloatArray()
+ >>> a
+ <vtkmodules.vtkCommonCore.vtkFloatArray(0x5653a6a6f700) at 0x7f0e7aecf5e0>
+
+If you call `str()` or `print()` on these objects, the wrappers will call the
+C++ `PrintSelf()` method. The printed information can be useful for debugging:
+
+ >>> o = vtkObject()
+ >>> print(o)
+ vtkObject (0x55858308a210)
+ Debug: Off
+ Modified Time: 85
+ Reference Count: 1
+ Registered Events: (none)
+
+### Other Classes (Special Types)
+
+VTK also uses several classes that aren't derived from `vtkObjectBase`. The
+most important of these is `vtkVariant`, which can hold any type of object:
+
+ >>> v1 = vtkVariant('hello')
+ >>> v1
+ vtkmodules.vtkCommonCore.vtkVariant('hello')
+ >>> v2 = vtkVariant(3.14)
+ >>> v2
+ vtkmodules.vtkCommonCore.vtkVariant(3.14)
+
+The wrapping of these classes is fully automatic, but is done in a slightly
+different manner than `vtkObjectBase`-derived classes. First, these classes
+have no `New()` method, and instead the public C++ constructors are wrapped
+to create an equivalent Python constructor. Second, the Python object
+contains its own copy of the C++ object, rather than containing just a
+pointer to the C++ object. The vast majority of these classes are lightweight
+containers and numerical types. For example, `vtkQuaterniond`, `vtkRectf`,
+`vtkColor4ub`, etc. Many of them are actually class templates, which are
+discussed below.
+
+When you apply `print()` or `str()` to these objects, the `operator<<` of the
+underlying C++ object is used to print them. For `repr()`, the name of the
+type name is printed, followed by the `str()` output in prentheses. The
+result looks similar to a constructor, though it might look strange depending
+on what `operator<<` produces.
+
+ >> v = vtkVariant()
+ >> print(repr(v))
+ vtkmodules.vtkCommonCore.vtkVariant((invalid))
+
+### Class Templates
+
+There are several C++ templates in VTK, which can be tricky to use from the
+wrappers since the Python language has no real concept of templates. The
+wrappers wrap templates as dictionary-like objects that map the template
+parameters to template instantiations:
+
+ >>> vtkSOADataArrayTemplate
+ <template vtkCommonCorePython.vtkSOADataArrayTemplate>
+ >>> vtkSOADataArrayTemplate.keys()
+ ['char', 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'int',
+ 'uint', 'int64', 'uint64', 'float32', 'float64']
+ >>> c = vtkSOADataArrayTemplate['float64']
+ >>> c
+ <class 'vtkmodules.vtkCommonCore.vtkSOADataArrayTemplate_IdE'>
+
+The wrappers instantiate the C++ template for a few useful types, as
+indicated by the `keys()` of the template. The Python type name also has a
+suffix (the '`IdE`') that indicates the template parameters in a compressed
+form according to IA64 C++ ABI name mangling rules, even when VTK is built
+with a compiler that does not use the IA64 ABI natively.
+
+Objects are created by first instantiating the template, and then
+instantiating the class:
+
+ >>> a = vtkSOADataArrayTemplate['float32']()
+ >>> a.SetNumberOfComponents(3)
+
+In the case of multiple template parameters, the syntax can look rather
+complicated, but really it isn't all that bad. For example, constructing
+a `vtkTuple<double,4>` in Python looks like this, with the template
+args in square brackets and the constructor args in parentheses:
+
+ >>> vtkTuple['float64',4]([1.0, 2.0, 3.0, 4.0])
+ vtkmodules.vtkCommonMath.vtkTuple_IdLi4EE([1.0, 2.0, 3.0, 4.0])
+
+The type names are the same as numpy's dtypes: `bool`, `int8`, `uint8`,
+`int16`, `uint16`, `int32`, `uint32`, `int64`, `uint64`, `float32`, and
+`float64`. Since `int64` is '`long long`', `int` is used for `long`. Also
+see [Template Keys](#template-keys) in [Advanced Topics](#internals-and-advanced-topics).
+
+
+## Method Calls
+
+When VTK methods are called from Python, conversion of all parameters from
+Python to C++ occurs automatically. That is, if the C++ method signature
+expects an integral type, you can pass a Python `int`, and if C++ expects a
+floating-point type, you can pass a Python `float` (or any type that allows
+implicit conversion to `float`).
+
+For C++ '`char`' parameters, which are rarely used in VTK, you must pass a
+string with a length of 1 or 0 bytes. This restricts the value to ASCII,
+since non-ASCII characters require at least 2 bytes in utf-8. An empty
+string signifies a null byte, and '\\0' can also be used.
+
+A Python `tuple`, `list`, or any other Python sequence can be passed to a VTK
+method that requires an array or `std::vector` in C++:
+
+ >>> a = vtkActor()
+ >>> p = (100.0, 200.0, 100.0)
+ >>> a.SetPosition(p)
+
+If the method is going to modify the array that you pass as a parameter,
+then you must pass a Python `list` that has the correct number of slots to
+accept the returned values. If you try this with a `tuple`, you will get a
+`TypeError` because `tuple` is immutable.
+
+ >>> z = [0.0, 0.0, 0.0]
+ >>> vtkMath.Cross((1,0,0),(0,1,0),z)
+ >>> print(z)
+ [0.0, 0.0, 1.0]
+
+For multi-dimensional array parameters, you can either use a nested list,
+or you can use numpy array with the correct shape.
+
+If the C++ method returns a pointer to an array, then in Python the method
+will return a tuple if the wrappers know the size of the array. In most
+cases, the size is hinted in the header file.
+
+ >>> a = vtkActor()
+ >>> print(a.GetPosition())
+ (0.0, 0.0, 0.0)
+
+Finally, Python `None` is treated the same as C++ `nullptr`, which allows
+you to pass null objects and null strings:
+
+ >>> a = vtkActor()
+ >>> a.SetMapper(None)
+ >>> print(a.GetMapper())
+ None
+
+### Wrappable and Unwrappable Methods
+
+A method cannot be used from Python if its C++ parameters or return type
+cannot be converted to or from Python by the wrappers, or if the method is
+templated. Common non-convertible types include `std::ostream`, `std::istream`,
+and all STL container types except for `std::vector` (see below),
+and any non-trivial pointer type or any pointer to an object whose class is
+not derived from `vtkObjectBase`.
+
+The wrappable parameter types are:
+* `char`, wrapped as a single ASCII character in a Python `str`
+* `signed char` and `unsigned char`, wrapped as Python `int`
+* `short`, `int`, `long` and `long long`, wrapped as Python `int`
+* `unsigned short` to `unsigned long long`, wrapped as Python `int`
+* `float` and `double`, wrapped as Python `float`
+* `size_t` and `ssize_t`, wrapped as Python `int`
+* `std::string`, wrapped as Python `str` via utf-8 encoding/decoding
+* typedefs of all the above, for any typedef defined in a VTK header file
+* `std::vector<T>` where `T` is one of the above, as Python `tuple` or `list`
+* `const T&` where `T` is any of the above, wrapped as described above
+* `T[N]` where `T` is a fundamental type, as Python `tuple` or `list`
+* `T[N][M]` where `T` is a fundamental type, as nested `tuple` or `list`
+* `T*` where `T` is a fundamental type, as `tuple` or `list`
+* `vtkObjectBase*` and derived types, as their respective Python type
+* `vtkSmartPointer<T>` as the Python vtkObjectBase-derived type `T`
+* `std::vector<vtkSmartPointer<T>>` as a sequence of objects of type `T`
+* `const std::vector<vtkSmartPointer<T>>` as a sequence of objects of type `T`
+* other wrapped classes (like `vtkVariant`), but not pointers to these types
+* `char*`, as Python `str` via utf-8 encoding/decoding
+* `void*`, as Python buffer (e.g. `bytes` or `bytearray`)
+* the parameter list `(void (*f)(void*), void*)` as a Python callable type
+
+References like `int&` and `std::string&` are wrapped via a reference proxy
+type as described in the [Pass by Reference](#pass-by-reference) section
+below. Non-const references to `std::vector<T>` and other mutable types
+do not use a proxy, but instead require that a mutable Python object is
+passed, for example a `list` rather than a `tuple`.
+
+A `void*` parameter can accept a pointer in two different ways: either from
+any Python object that supports the Python buffer protocol (this includes
+all numpy arrays along with the Python bytes and bytearray types), or from a
+string that contains a mangled pointer of the form '`_hhhhhhhhhhhh_p_void`'
+where '`hhhhhhhhhhhh`' is the hexadecimal address. Return-value `void*` will
+always be a string containing the mangled pointer.
+
+Also, a `T*` parameter for fundamental type `T` can accept a buffer object,
+if and only if it is annotated with the `VTK_ZEROCOPY` hint in the header file.
+With this hint, a numpy array of `T` can be passed to a `T*` parameter and
+the VTK method will directly access the memory buffer of the array. Hence the
+name 'zerocopy', which indicates no copying is done, and that direct memory
+access is used.
+
+The `vtkObject::AddObserver()` method has a special wrapping, as discussed
+in the [Observer Callbacks](#observer-callbacks) section below.
+
+### Conversion Constructors
+
+If a wrapped type has constructor that takes one parameter, and if that
+constructor is not declared '`explicit`', then the wrappers will automatically
+use that constructor for type conversion to the parameter type. The
+wrappers ensure that this conversion occurs in Python in the same manner
+that it is expected to occur in C++.
+
+For example, `vtkVariantArray` has a method `InsertNextItem(v:vtkVariant)`,
+and `vtkVariant` has a constructor `vtkVariant(x:int)`. So, you can do this:
+
+ >>> variantArray.InsertNextItem(1)
+
+The wrappers will automatically construct a `vtkVariant` from '`1`', and
+will then pass it as a parameter to `InsertNextItem()`. This is a feature
+that most C++ programmers will take for granted, but Python users might
+find it surprising.
+
+### Overloaded Methods
+
+If you call a VTK method that is overloaded, the Python wrappers will choose
+the overload that best matches the supplied arguments. This matching takes
+into account all allowed implicit conversions, such as int to float or any
+conversion constructors that are defined for wrapped objects.
+
+Some overloads will be unavailable (not wrapped) either because they are
+unwrappable as per the criteria described above, or because they are shadowed
+by another overload that is always preferable. A simple example of this is
+any methods that is overloaded on C++ `float` and `double`. The Python
+`float` type is a perfect match C++ `double`, therefore the `float` overload
+is not wrapped.
+
+### Static Methods
+
+A static method can be called without an instance. For example,
+
+ vtkObject.SetGlobalWarningDisplay(1)
+
+Some VTK classes, like vtkMath, consist solely of static methods. For others,
+like `vtkMatrix4x4`, most of the non-static methods have static overloads.
+Within Python, the only way to tell if a VTK method is static (other than
+trying it) is to look at its docstring.
+
+### Unbound Methods
+
+When a non-static method is called on the class, rather than on an instance,
+it is called an unbound method call. An unbound method call must provide
+'self' as the first argument, where 'self' is an instance of either the class
+or a subclass.
+
+ w = vtkRenderWindow()
+ vtkWindow.Render(w)
+
+In other words, the wrappers translate Python unbound method calls into
+C++ unbound method calls. These are useful when deriving a Python class
+from a wrapped VTK class, since they allow you to call any base class
+methods that have been overridden in the subclass.
+
+### Operator Methods
+
+For special classes (the ones not derived from `vtkObjectBase`), some useful
+C++ operators are wrapped in python. The '`[]`' operator is wrapped for
+indexing and item assignment, but because it relies on hints to guess which
+indices are out-of-bounds, it is only wrapped for `vtkVector` and related
+classes.
+
+The comparison operators '`<`' '`<=`' '`==`' '`>=`' '`>`' are wrapped for all
+classes that have these operators in C++. These operators allow sorting
+of `vtkVariant` objects with Python.
+
+The '`<<`' operator for printing is wrapped and is used by the python
+`print()` and `str()` commands.
+
+### Strings and Bytes
+
+VTK uses both `char*` and `std::string` for strings. As far as the wrappers
+are concerned, these are equivalent except that the former can be `nullptr`
+(`None` in Python). For both, the expected encoding is ASCII or utf-8.
+
+In Python, either `str` or `bytes` can be used to store strings, and both
+of these can be passed to VTK methods that require `char*` or `std::string`
+(or the legacy `vtkStdString`). A `str` object is passed to VTK as utf-8,
+while a `bytes` object is passed as-is.
+
+When a VTK method returns a string, it is received in Python as a `str` object
+if it is valid utf-8, or as a `bytes` object if not. The caller should check
+the type of the returned object (`str`, `bytes`, or perhaps `None`) if there
+is any reason to suspect that non-utf-8 text might be present.
+
+### STL Containers
+
+VTK provides conversion between `std::vector` and Python sequences
+such as `tuple` and `list`. If the C++ method returns a vector,
+the Python method will return a tuple:
+
+ C++: const std::vector<std::string>& GetPaths()
+ C++: std::vector<std::string> GetPaths()
+ Python: GetPaths() -> Tuple[str]
+
+If the C++ method accepts a vector, then the Python method can be
+passed any sequence with compatible values:
+
+ C++: void SetPaths(const std::vector<std::string>& paths)
+ C++: void SetPaths(std::vector<std::string> paths)
+ Python: SetPaths(paths: Sequence[str]) -> None
+
+Furthermore, if the C++ method accepts a non-const vector reference,
+then the Python method can be passed a mutable sequence (e.g. `list`):
+
+ C++: void GetPaths(std::vector<std::string>& paths)
+ Python: GetPaths(paths: MutableSequence[str]) -> None
+
+The value type of the `std::vector<T>` must be `std::string` or a
+fundamental numeric type such as `double` or `int` (including
+`signed char` and `unsigned char` but excluding `char`).
+
+### Smart pointers
+
+The wrappers will automatically convert between C++ `vtkSmartPointer<T>`
+and objects of type `T` (or `None`, if the smart pointer is empty):
+
+ C++: vtkSmartPointer<vtkObject> TakeObject()
+ Python: TakeObject() -> vtkObject
+
+In other words, in Python the smart pointer doesn't look any different
+from the object it points to. Under the hood, however, the wrappers
+understand that the smart pointer carries a reference to the object and
+will take responsibility for deleting that reference.
+
+A C++ method can return a vector of smart pointers, which will be seen in
+Python as a tuple of objects:
+
+ C++: std::vector<vtkSmartPointer<vtkObject>> GetObjects()
+ Python: GetObject() -> Tuple[vtkObject]
+
+If a C++ method expects `std::vector<vtkSmartPointer<T>>` as a parameter,
+the wrappers will automatically construct the vector from any sequence that
+is passed from Python. The objects in the sequence must be of type `T` (or
+a subclass of `T`, or `None`). If not, a `TypeError` will be raised.
+
+### Pass by Reference
+
+Many VTK methods use pass-by-reference to return values back to the caller.
+Calling these methods from Python requires special consideration, since
+Python's `str`, `tuple`, `int`, and `float` types are immutable. The wrappers
+provide a '`reference`' type, which is a simple container that allows
+pass-by-reference.
+
+For example, consider the following C++ method that uses pass-by-reference:
+
+ void GetCellAtId(vtkIdType cellId, vtkIdType& cellSize, vtkIdType const*& cellPoints)
+
+It requires a reference to `vtkIdType` (a Python `int`), and to
+`vtkIdType const*` (a tuple of `int`s). So we can call this method as
+follows:
+
+ >>> from vtkmodules.vtkCommonCore import reference
+ >>> from vtkmodules.vtkCommonDataModel import vtkCellArray
+ >>>
+ >>> # Build a cell array
+ >>> a = vtkCellArray()
+ >>> a.InsertNextCell(3, (1, 3, 0))
+ >>>
+ >>> # Create the reference objects
+ >>> n = reference(0)
+ >>> t = reference((0,))
+ >>>
+ >>> # Call the pass-by-reference method
+ >>> a.GetCellAtId(0, n, t)
+ >>>
+ >>> n.get()
+ 3
+ >>> t.get()
+ (1, 3, 0)
+
+Some important notes when using pass-by-reference:
+1. The reference constructor must be given a value of the desired type.
+ The method might use this value or might ignore it.
+2. Calling the `get()` method of the reference is usually unnecessary,
+ because the reference already supports the interface protocols of the
+ object that it contains.
+
+### Preconditions
+
+One very real concern when using VTK from Python is that the parameters that
+you pass to a method might cause the program to crash. In particular, it is
+very easy to pass an index that causes an out-of-bounds memory access, since
+the C++ methods don't do bounds checking. As a safety precaution, the
+wrappers perform the bounds check before the C++ method is called:
+
+ >>> a = vtkFloatArray()
+ >>> a.GetValue(10)
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in <module>
+ ValueError: expects 0 <= id && id < GetNumberOfValues()
+
+All precondition checks raise a `ValueError` if they fail, since they are
+checks on the values of the parameters. The wrappers don't know if C++ is
+using the parameter as an index, so `IndexError` is not used.
+
+Currently the only way to find out if a method has preconditions is to look
+at the declaration of the method in the C++ header file to see if it has a
+`VTK_EXPECTS` hint.
+
+## Observer Callbacks
+
+Similar to what can be done in C++, a Python function can be called
+each time a VTK event is invoked on a given object. In general, the
+callback function should have the signature `func(obj:vtkObject, event:str)`,
+or `func(self, obj:vtkObject, event:str)` if it is a method of a class.
+
+ >>> def onObjectModified(object, event):
+ >>> print('object: %s - event: %s' % (object.GetClassName(), event))
+ >>>
+ >>> o = vtkObject()
+ >>> o.AddObserver(vtkCommand.ModifiedEvent, onObjectModified)
+ 1
+ >>> o.Modified()
+ object: vtkObject - event: ModifiedEvent
+
+
+### Call Data
+
+In case there is a 'CallData' value associated with an event, in C++, you
+have to cast it from `void*` to the expected type using `reinterpret_cast`.
+The equivalent in python is to add a `CallDataType` attribute to the
+associated python callback method. The supported `CallDataType` values are
+`VTK_STRING`, `VTK_OBJECT`, `VTK_INT`, `VTK_LONG`, `VTK_DOUBLE`, and
+`VTK_FLOAT`.
+
+The following example uses a function as a callback, but a method or any
+callable object can be used:
+
+ >>> from vtkmodules.vtkCommonCore import vtkCommand, VTK_INT
+ >>>
+ >>> def onError(object, event, calldata):
+ >>> print('object: %s - event: %s - msg: %s' % (object.GetClassName(), event, calldata))
+ >>>
+ >>> onError.CallDataType = VTK_INT
+ >>>
+ >>> lt = vtkLookupTable()
+ >>> lt.AddObserver(vtkCommand.ErrorEvent, onError)
+ 1
+ >>> lt.SetTableRange(2,1)
+ object: vtkLookupTable - event: ErrorEvent - msg: ERROR:
+ In /home/user/VTK/Common/Core/vtkLookupTable.cxx, line 122
+ vtkLookupTable (0x6b40b30): Bad table range: [2, 1]
+
+For convenience, the `CallDataType` can also be specified where the function
+is first declared with the help of the `@calldata_type` decorator:
+
+ >>> from vtkmodules.util.misc import calldata_type
+ >>>
+ >>> @calldata_type(VTK_INT)
+ >>> def onError(object, event, calldata):
+ >>> print('object: %s - event: %s - msg: %s' % (object.GetClassName(),
+ event, calldata))
+
+## Other Wrapped Entities
+
+### Constants
+
+Most of the constants defined in the VTK header files are available in Python,
+and they can be accessed from the module in which they are defined. Many of
+these are found in the `vtkCommonCore` module, where they were defined as
+preprocessor macros.
+
+ >>> from vtkmodules.vtkCommonCore import VTK_DOUBLE_MAX
+ >>> VTK_DOUBLE_MAX
+ 1.0000000000000001e+299
+
+Others are defined as enums, often within a class namespace. If the enum
+is anonymous, then its values are `int`.
+
+ >>> vtkCommand.ErrorEvent
+ 39
+
+Constants in the header files are wrapped if they are enums, or if they are
+const variables of a wrappable scalar type, or if they are preprocessor
+symbols that evaluate to integer, floating-point, or string literal types.
+
+### Enum Types
+
+Each named enum type is wrapped as a new Python type, and members of the enum
+are instances of that type. This allows type checking for enum types:
+
+ >>> from vtkmodules.vtkCommonColor import vtkColorSeries
+ >>> vtkColorSeries.COOL
+ 2
+ >>> isinstance(vtkColorSeries.ColorSchemes, vtkColorSeries.COOL)
+ >>> cs = vtkColorSeries()
+ >>> cs.SetColorScheme(vtkColorSeries.COOL)
+
+Enum classes are wrapped in a manner similar to named enums, except that
+the enum values are placed within the enum class namespace. For example,
+`vtkEventDataAction` is an enum class, with '`Press`' as a member:
+
+ >>> from vtkmodules.vtkCommonCore import vtkEventDataAction
+ >>> vtkEventDataAction.Press
+ 1
+ >>> isinstance(vtkEventDataAction.Press, vtkEventDataAction)
+ True
+
+In the first example, the `ColorSchemes` enum type and the `COOL` enum value
+were both defined in the `vtkColorSeries` namespace. In the second example,
+the `vtkEventDataAction` enum class was defined in the module namespace,
+and the `Press` value was defined in the enum class namespace.
+
+Note that the VTK enum types behave like C++ enums, and not like the Python
+enums types provided by the Python '`enum`' module. In particular, all VTK
+enum values can be used anywhere that an `int` can be used.
+
+### Namespaces
+
+Namespaces are currently wrapped in a very limited manner. The only
+namespace members that are wrapped are enum constants and enum types.
+There is no wrapping of namespaced classes or functions, or of nested
+namespaces. Currently, the wrappers implement namespaces as Python
+`module` objects.
+
+
+## Docstrings
+
+The wrappers automatically generate docstrings from the doxygen comments in
+the header files. The Python `help()` command can be used to print the
+documentation to the screen, or the `__doc__` attributes of the classes
+and methods can be accessed directly.
+
+### Method Docstrings
+
+The method docstrings are formatted with the method signatures first,
+followed by doxygen comments. The Python method signatures have type
+annotations, and are followed by the C++ method signatures for
+completeness.
+
```
+ InvokeEvent(self, event:int, callData:Any) -> int
+ C++: int InvokeEvent(unsigned long event, void* callData)
+ InvokeEvent(self, event:str, callData:Any) -> int
+ C++: int InvokeEvent(const char* event, void* callData)
+ InvokeEvent(self, event:int) -> int
+ C++: int InvokeEvent(unsigned long event)
+ InvokeEvent(self, event:str) -> int
+ C++: int InvokeEvent(const char* event)
+
+ This method invokes an event and returns whether the event was
+ aborted or not. If the event was aborted, the return value is 1,
+ otherwise it is 0.
+```
+
+Some Python IDEs will automatically show the docstring as soon as you type
+the name of the method.
+
+### Class Docstrings
+
+The class docstrings include a brief description of the class, followed
+by the name of the superclass, and then the full doxygen documentation,
+including doxygen markup:
+
+```
+ vtkMatrix4x4 - represent and manipulate 4x4 transformation matrices
+
+ Superclass: vtkObject
+
+ vtkMatrix4x4 is a class to represent and manipulate 4x4 matrices.
+ Specifically, it is designed to work on 4x4 transformation matrices
+ found in 3D rendering using homogeneous coordinates [x y z w]. Many
+ of the methods take an array of 16 doubles in row-major format. Note
+ that OpenGL stores matrices in column-major format, so the matrix
+ contents must be transposed when they are moved between OpenGL and
+ VTK.
+ @sa
+ vtkTransform
+```
+
+If the class is not derived from `vtkObjectBase`, then it will have one or
+more public constructors, and these will be included before the comments:
+
+```
+ vtkSimpleCriticalSection() -> vtkSimpleCriticalSection
+ C++: vtkSimpleCriticalSection()
+ vtkSimpleCriticalSection(isLocked:int) -> vtkSimpleCriticalSection
+ C++: vtkSimpleCriticalSection(int isLocked)
+
+ vtkSimpleCriticalSection - Critical section locking class
+
+ vtkCriticalSection allows the locking of variables which are accessed
+ through different threads.
+```
+
+### Template Docstrings
+
+Class templates are documented similar to classes, except that they include
+a 'Provided Types' section that lists the available template instantiations
+and the C++ template arguments that they correspond to.
+
+```
+ vtkSOADataArrayTemplate - Struct-Of-Arrays implementation of
+ vtkGenericDataArray.
+
+ Superclass: vtkGenericDataArray[vtkSOADataArrayTemplate[ValueTypeT],ValueTypeT]
+
+ vtkSOADataArrayTemplate is the counterpart of vtkAOSDataArrayTemplate.
+ Each component is stored in a separate array.
+
+ @sa
+ vtkGenericDataArray vtkAOSDataArrayTemplate
+
+
+ Provided Types:
+
+ vtkSOADataArrayTemplate[char] => vtkSOADataArrayTemplate<char>
+ vtkSOADataArrayTemplate[int8] => vtkSOADataArrayTemplate<signed char>
+ vtkSOADataArrayTemplate[uint8] => vtkSOADataArrayTemplate<unsigned char>
+ vtkSOADataArrayTemplate[int16] => vtkSOADataArrayTemplate<short>
+ vtkSOADataArrayTemplate[uint16] => vtkSOADataArrayTemplate<unsigned short>
+ vtkSOADataArrayTemplate[int32] => vtkSOADataArrayTemplate<int>
+ vtkSOADataArrayTemplate[uint32] => vtkSOADataArrayTemplate<unsigned int>
+ vtkSOADataArrayTemplate[int] => vtkSOADataArrayTemplate<long>
+ vtkSOADataArrayTemplate[uint] => vtkSOADataArrayTemplate<unsigned long>
+ vtkSOADataArrayTemplate[int64] => vtkSOADataArrayTemplate<long long>
+ vtkSOADataArrayTemplate[uint64] => vtkSOADataArrayTemplate<unsigned long long>
+ vtkSOADataArrayTemplate[float32] => vtkSOADataArrayTemplate<float>
+ vtkSOADataArrayTemplate[float64] => vtkSOADataArrayTemplate<double>
+```
+
+Unlike classes, the template documentation is formatted similarly regardless
+of whether the the class template derives from `vtkObjectBase` or not:
+
+```
+ vtkVector - templated base type for storage of vectors.
+
+ Superclass: vtkTuple[T,Size]
+
+ This class is a templated data type for storing and manipulating fixed
+ size vectors, which can be used to represent two and three dimensional
+ points. The memory layout is a contiguous array of the specified type,
+ such that a float[2] can be cast to a vtkVector2f and manipulated. Also
+ a float[6] could be cast and used as a vtkVector2f[3].
+
+
+ Provided Types:
+
+ vtkVector[float64,4] => vtkVector<double, 4>
+ vtkVector[float32,4] => vtkVector<float, 4>
+ vtkVector[int32,4] => vtkVector<int, 4>
+ vtkVector[float64,2] => vtkVector<double, 2>
+ vtkVector[float32,2] => vtkVector<float, 2>
+ vtkVector[int32,2] => vtkVector<int, 2>
+ vtkVector[float64,3] => vtkVector<double, 3>
+ vtkVector[float32,3] => vtkVector<float, 3>
+ vtkVector[int32,3] => vtkVector<int, 3>
+```
+
+
+## Internals and Advanced Topics
+
+### Special Attributes
+
+Classes and objects derived from `vtkObjectBase` have special attributes, which
+are only used in very special circumstances.
+
+The `__vtkname__` attribute of the class provides the same string that the
+GetClassName() method returns. With the exception of classes that are
+template instantiations, it is identical to the `__name__` attribute.
+For template instantiations, however, `GetClassName()` and `__vtkname__`
+return the result of calling `typeid(cls).name()` from C++, which provides
+a platform specific result:
+
+ >>> vtkSOADataArrayTemplate['float32'].__vtkname__
+ '23vtkSOADataArrayTemplateIfE'
+
+This can be used to get the VTK `ClassName` when you don't have an
+instantiation to call `GetClassName()` on. It is useful for checking the
+type of a C++ VTK object against a Python VTK class.
+
+The `__this__` attribute of the objects is a bit less esoteric, it provides a
+pointer to the C++ object as a mangled string:
+
+ >>> a = vtkFloatArray()
+ >>> a.__this__
+ '_00005653a6a6f700_p_vtkFloatArray'
+
+The string provides the hexadecimal address of '`this`', followed by '`p`'
+(shorthand for *pointer*), and the type of the pointer. You can also
+construct a Python object directly from the C++ address, if the address is
+formatted as described above:
+
+ >>> a = vtkFloatArray('_00005653a6a6f700_p_vtkFloatArray')
+ >>> a
+ <vtkmodules.vtkCommonCore.vtkFloatArray(0x5653a6a6f700) at 0x7f0e7aecf5e0>
+
+If you call the constructor on the string provided by `__this__`, you will
+get exactly the same Python object back again, rather than a new object.
+But this constructor can be useful if you have some VTK code that has been
+wrapped with a different wrapper tool, for example with SWIG. If you can
+get the VTK pointer from SWIG, you can use it to construct Python object
+that can be used with the native VTK wrappers.
+
+### Wrapper Hints
+
+A wrapper hint is an attribute that can be added to a class, method, or
+parameter declaration in a C++ header file to give extra information to
+the wrappers. These hints are defined in the `vtkWrappingHints.h` header
+file.
+
+The following hints can appear before a method declaration:
+* `VTK_WRAPEXCLUDE` excludes a method from the wrappers
+* `VTK_NEWINSTANCE` passes ownership of a method's return value to the caller
+
+For convenience, `VTK_WRAPEXCLUDE` can also be used to exclude a whole class.
+The `VTK_NEWINSTANCE` hint is used when the return value is a `vtkObjectBase*`
+and the caller must not increment the reference count upon acceptance of the
+object (but must still decrement the reference count when finished with the
+object).
+
+The following hints can appear after a method declaration:
+* `VTK_EXPECTS(cond)` provides preconditions for the method call
+* `VTK_SIZEHINT(expr)` marks the array size of a return value
+* `VTK_SIZEHINT(name, expr)` marks the array size of a parameter
+
+For `VTK_EXPECTS(cond)`, the precondition must be valid C++ code, and can
+use any of the parameter names or `this`. Even without `this`, any public
+names in the class namespace (including method names) will be resolved.
+See the [Preconditions](#preconditions) section for additional information.
+
+`VTK_SIZEHINT(expr)` is used for methods that return an array as type `T*`,
+where `T` is a numeric data type. The hint allows the wrappers to convert the
+array to a tuple of the correct size. Without the size hint, the wrappers
+will return the pointer as a string that provides a mangled memory address
+of the form '`_hhhhhhhhhhhh_p_void`' where '`hhhhhhhhhhhh`' is address
+expressed in hexadecimal.
+
+`VTK_SIZEHINT(parameter_name, expr)` is used to hint parameters of type
+`T*` or `T&*` (with `T` as a numeric data type) so that the wrappers know
+the size of the array that the pointer is pointing to. The `expr` can be
+any expression that evaluates to an integer, and it can include parameter
+names, public class members and method calls, or the special name `_`
+(underscore) which indicates the method's return value. In the absence
+of a size hint, the wrappers cannot check that the length of the sequence
+passed from Python matches the size of the array required by the method.
+If the method requires a larger array than it receives, a buffer overrun
+will occur.
+
+The following hints can appear before a parameter declaration:
+* `VTK_FILEPATH` marks a parameter that accepts a pathlib.Path object
+* `VTK_ZEROCOPY` marks a parameter that accepts a buffer object
+
+More specifically, `VTK_FILEPATH` is used with `char*` and `std::string`
+parameters to indicate that the method also accepts any object with a
+`__fspath__()` method that returns a path string. And `VTK_ZEROCOPY` is
+used with `T*` parameters, for basic integer or float type `T`, to indicate
+that the Python buffer protocol will be used to access the values, rather
+than the Python sequence protocol that is used by default.
+
+### Deprecation Warnings
+
+In addition to the wrapping hints, the Python wrappers are also aware of the
+deprecation attributes that have been applied to classes and methods. When
+a deprecated method is called, a `DeprecationWarning` is generated and
+information about the deprecation is printed, including the VTK version
+for the deprecation.
+
+To ignore these warnings, use the following code:
+
+ import warnings
+ warnings.filterwarnings('ignore', category=DeprecationWarning)
+
+To see each deprecation warning just once per session,
+
+ warnings.filterwarnings('once', category=DeprecationWarning)
+
+### Template Keys
+
+The following is a table of common template key names, which are the same as
+the numpy dtype names. Note that you can actually use numpy dtypes as keys,
+as well as the native Python types `bool`, `int`, and `float`. There is
+some danger in using `int`, however, because it maps to C++ `long` which has
+a platform-dependent size (either 32 bits or 64 bits). Finally, the char
+codes from the Python `array` module can be used as keys, but they should
+be avoided since more programmers are familiar with numpy than with the
+much older `array` module.
+
+| C++ Type | Template Key | Type Key | Char Key | IA64 ABI Code |
+| ------------------ | ------------ | -------- | -------- | ------------- |
+| bool | 'bool' | bool | '?' | IbE |
+| char | 'char' | | 'c' | IcE |
+| signed char | 'int8' | | 'b' | IaE |
+| unsigned char | 'uint8' | | 'B' | IhE |
+| short | 'int16' | | 'h' | IsE |
+| unsigned short | 'uint16' | | 'H' | ItE |
+| int | 'int32' | | 'i' | IiE |
+| unsigned int | 'uint32' | | 'I' | IjE |
+| long | 'int' | int | 'l' | IlE |
+| unsigned long | 'uint' | | 'L' | ImE |
+| long long | 'int64' | | 'q' | IxE |
+| unsigned long long | 'uint64' | | 'Q' | IyE |
+| float | 'float32' | | 'f' | IfE |
+| double | 'float64' | float | 'd' | IdE |
+
+Since the size of '`long`' and '`unsigned long`' is platform-dependent, these
+types should generally be avoided.
+
+### Exception Handling
+
+There are times when an observer might generate a Python exception. Since
+the observers are called from C++, there is no good way to catch these
+exceptions from within Python. So, instead, the wrappers simply print a
+traceback to stderr and then clear the error indicator. The Python program
+will continue running unless the exception was a `KeyboardInterrupt` (Ctrl-C),
+in which case the program will exit with an error code of 1.
+
+### Deleting a vtkObject
+
+There is no direct equivalent of VTK's `Delete()` method, since Python does
+garbage collection automatically. The Python object will be deleted
+when there are no references to it within Python, and the C++ object will
+be deleted when there are no references to it from within either Python
+or C++. Note that references can hide in unexpected places, for example if
+a method of an object is used as an observer callback, the object will not
+be deleted until the observer is disconnected.
+
+The `DeleteEvent` can be used to detect object deletion, but note that the
+observer will receive a None for the object, since the observer is called
+after (not before) the deletion occurs:
+
+ >>> o = vtkObject()
+ >>> o.AddObserver('DeleteEvent', lambda o,e: print(e, o))
+ 1
+ >>> del o
+ DeleteEvent None
+
+If you need to know what object is deleted, the identifying information must
+be extracted before the deletion occurs:
+
+ >>> o = vtkObject()
+ >>> o.AddObserver('DeleteEvent',lambda x,e,r=repr(o): print(e, r))
+ 1
+ >>> del o
+ DeleteEvent <vtkmodules.vtkCommonCore.vtkObject(0x55783870f970) at 0x7f1e61678be0>
+
+In cases where you need to track down tricky memory issues, you might find
+it useful to call the `GetReferenceCount()` method of the object directly.
+
+### Ghosts
+
+A wrapped VTK object (derived from `vtkObjectBase`) is a Python object that
+holds a pointer to a C++ object (specifically, a `vtkObjectBase*`). The
+Python object can have attributes that the C++ object knows nothing about.
+So, what happens to these attributes if the Python object is deleted, but
+the C++ object lives on? Consider this simple example of storing the C++
+object in an array and then deleting the Python object:
+
+ obj = vtkObject()
+ obj.tag = 'FirstObject'
+ va = vtkVariantArray()
+ va.InsertNextValue(obj)
+ del obj
+
+When we retrieve the object from the array, we want it to have the '`tag`'
+attributes that it had we stored it. But you might wonder, aren't all
+Python-specific attributes deleted along with the Python object? The
+answer is, no they aren't, they're saved until until the C++ object itself
+is deleted.
+
+The wrappers have a special place, which we will call the graveyard, where
+'ghosts' of objects are stored when the objects are deleted. The ghost is not
+an object, but rather a container for the Python attributes of a deceased
+object. If the object ever reappears within Python, usually as a return
+value from a C++ method call, then the ghost is resurrected as a new Python
+object that has all the attributes of the original Python object.
+
+The graveyard is only used for objects that have unfinished business. If a
+Python object has an empty dict and no other special attributes, then it will
+not go to the graveyard. Also, if the C++ object is deleted at the same time
+as the Python object, then the graveyard will not be used. Each ghost in the
+graveyard holds a weak pointer to its C++ object and will vanish when the C++
+object is deleted (not immediately, but the next time the graveyard garbage
+collector runs).
+
+### Subclassing a VTK Class
+
+It is possible to subclass a VTK class from within Python, but this is of
+limited use because the C++ virtual methods are not hooked to the Python
+methods. In other words, if you make a subclass of `vtkPolyDataAlgorithm`
+and override override the `Execute()` method, it will not be automatically
+called by the VTK pipeline. Your `Execute()` method will only be called if
+the call is made from Python.
+
+The addition of virtual method hooks to the wrappers has been proposed,
+but currently the only way for Python methods to be called from C++ code
+is via callbacks. The `vtkProgrammableSource` and `vtkProgrammableFilter` are
+examples of VTK algorithm classes that use callbacks for execution, while
+`vtkInteractionStyleUser` can use observer callbacks for event handling.
+
+### Wrapping External VTK Modules
+
+If you have your own C++ classes that are based on VTK, and if they are
+placed with a VTK module with a vtk.module file, then they can be wrapped
+as shown in the [Module Wrapping Example][external-wrapping]. You will
+also find the cmake documentation on VTK modules to be useful.
+
+[external-wrapping]: https://gitlab.kitware.com/vtk/vtk/-/blob/release/Examples/Modules/Wrapping
+
+## Experimental Features
+
+### Python Class Overrides
+
+VTK now supports overriding wrapped classes with Python subclasses. This
+enables developers to provide more Python friendly interfaces for certain
+classes. Here is a trivial example of an override:
+
+ from vtkmodules.vtkCommonCore import vtkPoints
+ @vtkPoints.override
+ class CustomPoints(vtkPoints):
+ pass
+
+Once the override is in place, any future `vtkPoints` Python object instances
+will be instances of the override class. This behavior is global.
+
+ points = vtk.vtkPoints() # returns an instance of CustomPoints
+
+The override can be reversed by setting an override of `None`, but this will
+not impact instantiations that have already occurred.
+
+ vtkPoints.override(None)
+
+If the class has already been overridden in C++ via VTK's object factory
+mechanism, then directly applying a Python override to that class will not
+work. Instead, the Python override must be applied to the C++ factory
+override. For example, on Windows,
+
+ @vtkWin32OpenGLRenderWindow.override
+ class CustomRenderWindow(vtkWin32OpenGLRenderWindow):
+ ...
+ window = vtkRenderWindow() # creates a CustomRenderWindow
+
+Please see [Subclassing a VTK Class](#subclassing-a-vtk-class) for restrictions on
+subclassing VTK classes through Python.
+
+
+### Stub Files for Type Hinting
+
+VTK includes a script called [`generate_pyi.py`][generate_pyi] that
+will generate pyi stub files for each wrapped VTK module. The purpose of
+these files, as explained in [PEP 484][pep_484], is to provide type
+information for all constants, classes, and methods in the modules.
+Each of these files contain blocks like this:
+
+ VTK_DOUBLE:int
+ VTK_DOUBLE_MAX:float
+ VTK_DOUBLE_MIN:float
+ ...
+
+ class vtkObject(vtkObjectBase):
+ def AddObserver(self, event:int, command:Callback, priority:float=0.0) -> int: ...
+ def GetMTime(self) -> int: ...
+ @staticmethod
+ def GetNumberOfGenerationsFromBaseType(type:str) -> int: ...
+ @overload
+ def HasObserver(self, event:int, __b:'vtkCommand') -> int: ...
+ @overload
+ def HasObserver(self, event:str, __b:'vtkCommand') -> int: ...
+
+ class vtkAbstractArray(vtkObject):
+ class DeleteMethod(int): ...
+ VTK_DATA_ARRAY_ALIGNED_FREE:'DeleteMethod'
+ VTK_DATA_ARRAY_DELETE:'DeleteMethod'
+ VTK_DATA_ARRAY_FREE:'DeleteMethod'
+ VTK_DATA_ARRAY_USER_DEFINED:'DeleteMethod'
+ def Allocate(self, numValues:int, ext:int=1000) -> int: ...
+
+Python consoles like ipython and IDEs like PyCharm can use the information in
+these files to provide hints while you edit the code. These files are
+included in the Python packages for VTK, but they can also be built by
+executing the `generate_pyi.py` script. To do so, execute the script
+with the `vtkpython` executable (or with the regular python executable,
+if its paths are set for VTK):
+
+ vtkpython -m vtkmodules.generate_pyi
+
+This will place build the pyi files and place them inside the `vtkmodules`
+package, where ipython and PyCharm should automatically find them. The
+help for this script is as follows:
+
+ usage: python generate_pyi.py [-p package] [-o output_dir] [module ...]
+ options:
+ -p NAME Package name [vtkmodules by default].
+ -o OUTPUT Output directory [package directory by default].
+ -e EXT Output file suffix [.pyi by default].
+ module Module or modules to process [all by default].
+
+The pyi files are syntactically correct python files, so it is possible to
+load them as such in order to test them and inspect them.
+
+[generate_pyi]: https://gitlab.kitware.com/vtk/vtk/-/blob/release/Wrapping/Python/vtkmodules/generate_pyi.py
+[pep_484]: https://www.python.org/dev/peps/pep-0484/#stub-files
diff --git a/Documentation/dev/build_documentation.md b/Documentation/docs/advanced/build_documentation.md
similarity index 100%
rename from Documentation/dev/build_documentation.md
rename to Documentation/docs/advanced/build_documentation.md
diff --git a/Documentation/dev/build_for_mobile.md b/Documentation/docs/advanced/build_for_mobile.md
similarity index 89%
rename from Documentation/dev/build_for_mobile.md
rename to Documentation/docs/advanced/build_for_mobile.md
index d6d8c95ce1b63b16b90f18482c7859607e7c6499..7a60c43c8fd1f85e6c6f2df2b0f7b59d08b55a3e 100644
--- a/Documentation/dev/build_for_mobile.md
+++ b/Documentation/docs/advanced/build_for_mobile.md
@@ -1,7 +1,7 @@
# Cross-compiling for Mobile devices
```{tip}
-For complete build instructions see [here](build.md).
+For complete build instructions see [here](../build_instructions/build.md).
```
VTK supports mobile devices in its build. These are triggered by a top-level
diff --git a/Documentation/dev/build_python_wheels.md b/Documentation/docs/advanced/build_python_wheels.md
similarity index 96%
rename from Documentation/dev/build_python_wheels.md
rename to Documentation/docs/advanced/build_python_wheels.md
index 77c74fe14e997c4d3f4b4c5871e318f97c5459f8..e9c58b4232ffae3b538bbc1fc048967eabfb254f 100644
--- a/Documentation/dev/build_python_wheels.md
+++ b/Documentation/docs/advanced/build_python_wheels.md
@@ -1,7 +1,7 @@
# Building Python Wheels
```{tip}
-For complete build instructions see [here](build.md).
+For complete build instructions see [here](../build_instructions/build.md).
```
VTK also supports creating a Python wheel containing its Python wrappers for
diff --git a/Documentation/dev/build_wasm_emscripten.md b/Documentation/docs/advanced/build_wasm_emscripten.md
similarity index 97%
rename from Documentation/dev/build_wasm_emscripten.md
rename to Documentation/docs/advanced/build_wasm_emscripten.md
index db65f50e099d06e8c534fe05deec8db73df44e12..ceb50ce1115f28ff0b3fc526f564a282fe9a43be 100644
--- a/Documentation/dev/build_wasm_emscripten.md
+++ b/Documentation/docs/advanced/build_wasm_emscripten.md
@@ -47,7 +47,7 @@ For this guide, you will need the following:
Alternatively the source-code can be obtained from the repository as well.
This is recommended only if you intent to make changes and contribute to
- VTK. Please refer to [git/develop.md](git/develop.md) for help with `git`.
+ VTK. Please refer to [git/develop.md](../developers_guide/git/develop.md) for help with `git`.
## Build project
diff --git a/Documentation/docs/advanced/migration_guides/ModuleMigration.md b/Documentation/docs/advanced/migration_guides/ModuleMigration.md
index 150803b51dc868103f7089c5045afeece99b9cd2..73c7ed07155f0ebcf8088106a7c3e5275537db94 100644
--- a/Documentation/docs/advanced/migration_guides/ModuleMigration.md
+++ b/Documentation/docs/advanced/migration_guides/ModuleMigration.md
@@ -1,2 +1,359 @@
-```{include} ../../../Doxygen/ModuleMigration.md
+# Module Migration from VTK 8.2 to 9+
+
+VTK 8.2 and older contained a module system which was based on variables and
+informed CMake's migration to target-based properties and interactions. This
+was incompatible with the way VTK ended up doing it. With VTK 9, its module
+system has been reworked to use CMake's targets.
+
+This document may be used as a guide to updating code using old VTK modules into
+code using new VTK modules.
+
+## Using modules
+
+If your project is just using VTK's modules and not declaring any of your own
+modules, porting involves a few changes to the way VTK is found and used.
+
+The old module system made variables available for using VTK.
+
+```cmake
+find_package(VTK
+ REQUIRED
+ COMPONENTS
+ vtkCommonCore
+ vtkRenderingOpenGL2)
+include(${VTK_USE_FILE})
+
+add_library(usesvtk ...)
+target_link_libraries(usesvtk ${visibility} ${VTK_LIBRARIES})
+target_include_directories(usesvtk ${visibility} ${VTK_INCLUDE_DIRS})
+
+# Pass any VTK autoinit defines to the target.
+target_compile_definitions(usesvtk PRIVATE ${VTK_DEFINITIONS})
```
+
+This causes problems if VTK is found multiple times within a source tree with
+different components. The new pattern is:
+
+```cmake
+find_package(VTK
+ #9.0 # Compatibility support is not provided if 9.0 is requested.
+ REQUIRED
+ COMPONENTS
+ # Old component names are OK, but deprecated.
+ #vtkCommonCore
+ #vtkRenderingOpenGL2
+ # New names reflect the target names in use.
+ CommonCore
+ RenderingOpenGL2)
+# No longer needed; warns or errors depending on the version requested when
+# finding VTK.
+#include(${VTK_USE_FILE})
+
+add_library(usesvtk ...)
+# VTK_LIBRARIES is provided for compatibility, but not recommended.
+#target_link_libraries(usesvtk ${visibility} ${VTK_LIBRARIES})
+target_link_libraries(usesvtk ${visibility} VTK::CommonCore VTK::RenderingOpenGL2)
+
+# Rather than defining a single `VTK_DEFINITIONS` for use by all relevant
+# targets, the definitions are made as needed with the exact set needed for the
+# listed modules.
+vtk_module_autoinit(
+ TARGETS usesvtk
+ #MODULES ${VTK_LIBRARIES} # Again, works, but is not recommended.
+ MODULES VTK::CommonCore VTK::RenderingOpenGL2)
+```
+
+## Module declaration
+
+The old module system had CMake code declare modules in `module.cmake` files.
+This allowed logic and other things to happen within them which could cause
+module dependencies to be hard to follow. The new module system now provides
+facilities for disabling modules in certain configurations (using `CONDITION`)
+and for optionally depending on modules (using `OPTIONAL_DEPENDS`).
+
+```cmake
+if (NOT SOME_OPTION)
+ set(depends)
+ if (SOME_OTHER_OPTION)
+ list(APPEND depends vtkSomeDep)
+ endif ()
+ vtk_module(vtkModuleName
+ GROUPS
+ # groups the module belongs to
+ KIT
+ # the kit the module belongs to
+ IMPLEMENTS
+ # modules containing vtkObjectFactory instances that are implemented here
+ DEPENDS
+ # public dependencies
+ #${depends} # no analogy in the new system
+ PRIVATE_DEPENDS
+ # private dependencies
+ ${depends}
+ COMPILE_DEPENDS
+ # modules which must be built before this one but which are not actually
+ # linked.
+ TEST_DEPENDS
+ # test dependencies
+ TEST_OPTIONAL_DEPENDS
+ # optional test dependencies
+ ${depends}
+ #EXCLUDE_FROM_WRAPPING
+ # present for modules which cannot be wrapped
+ )
+endif ()
+```
+
+This is now replaced with a declarative file named `vtk.module`. This file is
+not CMake code and is instead parsed as an argument list in CMake (variable
+expansions are also not allowed). The above example would translate into:
+
+```
+MODULE
+ vtkModuleName
+CONDITION
+ SOME_OPTION
+GROUPS
+ # groups the module belongs to
+KIT
+ # the kit the module belongs to
+#IMPLEMENTABLE # Implicit in the old build system. Now explicit.
+IMPLEMENTS
+ # modules containing vtkObjectFactory instances that are implemented here
+DEPENDS
+ # public dependencies
+PRIVATE_DEPENDS
+ # private dependencies
+OPTIONAL_DEPENDS
+ vtkSomeDep
+ORDER_DEPENDS
+ # modules which must be built before this one but which are not actually
+ # linked.
+TEST_DEPENDS
+ # test dependencies
+TEST_OPTIONAL_DEPENDS
+ # optional test dependencies
+ vtkSomeDep
+#EXCLUDE_WRAP
+ # present for modules which cannot be wrapped
+```
+
+Modules may also now be provided by the current project or by an external
+project found by `find_package` as well.
+
+## Declaring sources
+
+Sources used to be listed just as `.cxx` files. The module system would then
+search for a corresponding `.h` file, then add it to the list. Some source file
+properties could be used to control header-only or private headers.
+
+In this example, we have a module with the following sources:
+
+ - `vtkPublicClass.cxx` and `vtkPublicClass.h`: Public VTK class meant to be
+ wrapped and its header installed.
+ - `vtkPrivateClass.cxx` and `vtkPrivateClass.h`: Private VTK class not meant
+ for use outside of the module.
+ - `helper.cpp` and `helper.h`: Private API, but not following VTK's naming
+ conventions.
+ - `public_helper.cpp` and `public_helper.h`: Public API, but not following
+ VTK's naming conventions.
+ - `vtkImplSource.cxx`: A source file without a header.
+ - `public_header.h`: A public header without a source file.
+ - `template.tcc` and `template.h`: Public API, but not following VTK's naming
+ conventions.
+ - `private_template.tcc` and `private_template.h`: Private API, but not
+ following VTK's naming conventions.
+ - `vtkPublicTemplate.txx` and `vtkPublicTemplate.h`: Public template sources.
+ Wrapped and installed.
+ - `vtkPrivateTemplate.txx` and `vtkPrivateTemplate.h`: Private template
+ sources.
+ - `vtkOptional.cxx` and `vtkOptional.h`: Private API which requires an
+ optional dependency.
+
+The old module's way of building these sources is:
+
+```cmake
+set(Module_SRCS
+ vtkPublicClass.cxx
+ vtkPrivateClass.cxx
+ helper.cpp
+ helper.h
+ public_helper.cpp
+ public_helper.h
+ public_header.h
+ vtkImplSource.cxx
+ vtkPublicTemplate.txx
+ vtkPrivateTemplate.txx
+ template.tcc # Not detected as a template, so not installed.
+ template.h
+ private_template.tcc
+ private_template.h
+)
+
+# Mark some files as only being header files.
+set_source_files_properties(
+ public_header.h
+ HEADER_FILE_ONLY
+)
+
+# Mark some headers as being private.
+set_source_files_properties(
+ helper.h
+ private_template.h
+ public_header.h
+ template.h
+ vtkImplSource.cxx # no header
+ vtkPrivateTemplate.h
+ PROPERTIES SKIP_HEADER_INSTALL 1
+)
+
+set(${vtk-module}_HDRS # Magic variable
+ public_helper.h
+ template.h
+ #helper.h # private headers just go ignored.
+)
+
+# Optional dependencies are detected through variables.
+if (Module_vtkSomeDep)
+ list(APPEND Module_SRCS
+ # Some optional file.
+ vtkOptional.cxx)
+endif ()
+
+vtk_module_library(vtkModuleName ${Module_SRCS})
+```
+
+While with the new system, source files are explicitly declared using argument
+parsing.
+
+```cmake
+set(classes
+ vtkPublicClass)
+set(private_classes
+ vtkPrivateClass)
+set(sources
+ helper.cpp
+ public_helper.cpp
+ vtkImplSource.cxx)
+set(headers
+ public_header.h
+ public_helper.h
+ template.h)
+set(private_headers
+ helper.h
+ private_template.h)
+
+set(template_classes
+ vtkPublicTemplate)
+set(private_template_classes
+ vtkPrivateTemplate)
+set(templates
+ template.tcc)
+set(private_templates
+ private_template.tcc)
+
+# Optional dependencies are detected as targets.
+if (TARGET vtkSomeDep)
+ # Optional classes may not be public (though there's no way to actually
+ # enforce it, optional dependencies are always treated as private.
+ list(APPEND private_classes
+ vtkOptional)
+endif ()
+
+vtk_module_add_module(vtkModuleName
+ # File pairs which follow VTK's conventions. The headers will be wrapped and
+ # installed.
+ CLASSES ${classes}
+ # File pairs which follow VTK's conventions, but are not for use outside the
+ # module.
+ PRIVATE_CLASSES ${private_classes}
+ # Standalone sources (those without headers or which do not follow VTK's
+ # conventions).
+ SOURCES ${sources}
+ # Standalone headers (those without sources or which do not follow VTK's
+ # conventions). These will be installed.
+ HEADERS ${public_headers}
+ # Standalone headers (those without sources or which do not follow VTK's
+ # conventions), but are not for use outside the module.
+ PRIVATE_HEADERS ${private_headers}
+
+ # Templates are also supported.
+
+ # Template file pairs which follow VTK's conventions. Both files will be
+ # installed (only the headers will be wrapped).
+ TEMPLATE_CLASSES ${template_classes}
+ # Template file pairs which follow VTK's conventions, but are not for use
+ # outside the module.
+ PRIVATE_TEMPLATE_CLASSES ${private_template_classes}
+ # Standalone template files (those without headers or which do not follow
+ # VTK's conventions). These will be installed.
+ TEMPLATES ${templates}
+ # Standalone template files (those without headers or which do not follow
+ # VTK's conventions), but are not for use outside the module.
+ PRIVATE_TEMPLATES ${private_templates}
+)
+```
+
+Note that the arguments with `CLASSES` in their name expand to pairs of files
+with the `.h` and either `.cxx` or `.txx` extension based on whether it is a
+template or not. Projects not using this convention may use the `HEADERS`,
+`SOURCES`, and `TEMPLATES` arguments instead.
+
+## Object Factories
+
+Previously, object factories were made using implicit variable declaration magic
+behind the scenes. This is no longer the case and proper CMake APIs for them are
+available.
+
+```cmake
+set(sources
+ vtkObjectFactoryImpl.cxx
+ # This path is made by `vtk_object_factory_configure` later.
+ "${CMAKE_CURRENT_BINARY_DIR}/${vtk-module}ObjectFactory.cxx")
+
+# Make a list of base classes we will be overriding.
+set(overrides vtkObjectFactoryBase)
+# Make a variable declaring what the override for the class is.
+set(vtk_module_vtkObjectFactoryBase_override "vtkObjectFactoryImpl")
+# Generate a source using the list of base classes overridden.
+vtk_object_factory_configure("${overrides}")
+
+vtk_module_library("${vtk-module}" "${sources}")
+```
+
+This is now handled using proper APIs instead of variable lookups.
+
+```cmake
+set(classes
+ vtkObjectFactoryImpl)
+
+# Explicitly declare the override relationship.
+vtk_object_factory_declare(
+ BASE vtkObjectFactoryBase
+ OVERRIDE vtkObjectFactoryImpl)
+# Collects the set of declared overrides and writes out a source file.
+vtk_object_factory_declare(
+ # The path to the source is returned as a variable.
+ SOURCE_FILE factory_source
+ # As is its header file.
+ HEADER_FILE factory_header
+ # The export macro is now explicitly passed (instead of assumed based on the
+ # current module context).
+ EXPORT_MACRO MODULE_EXPORT)
+
+vtk_module_add_module(vtkModuleName
+ CLASSES ${classes}
+ SOURCES "${factory_source}"
+ PRIVATE_HEADERS "${factory_header}")
+```
+
+## Building a group of modules
+
+This was not well supported in the old module system. Basically, it involved
+setting up the source tree like VTK expects and then including the
+`vtkModuleTop` file. This is best just rewritten using the following CMake APIs:
+
+ - {cmake:command}`vtk_module_find_modules`
+ - {cmake:command}`vtk_module_find_kits`
+ - {cmake:command}`vtk_module_scan`
+ - {cmake:command}`vtk_module_build`
diff --git a/Documentation/docs/api/cmake/ModuleSystem.md b/Documentation/docs/api/cmake/ModuleSystem.md
index b5d828d437c893a9be24773ca6303a947c990066..8ae819714935735c77dc105fe512328200fc41f9 100644
--- a/Documentation/docs/api/cmake/ModuleSystem.md
+++ b/Documentation/docs/api/cmake/ModuleSystem.md
@@ -1,2 +1,1052 @@
-```{include} ../../../Doxygen/ModuleSystem.md
+# Module System
+
+VTK 9.0 introduces a new build system compared to previous versions. This
+version uses CMake's built-in functionality for behaviors that were performed
+manually in the previous iteration of the build system.
+
+## Terminology
+
+ - **module**: A unit of API provided by a project. This is the core of the
+ system and there are lots of features available through this mechanism that
+ are not provided by CMake's library or other usage requirements.
+ - **group**: A configure-time collection of modules. These may be used to
+ control whether member modules will be built or not with a single flag.
+ - **kit**: A collection of modules for which all the compiled code is placed
+ in a single library.
+ - **property**: An attribute of a module. Only of real interest to developers
+ of the module system and its extensions.
+ - **autoinit**: A mechanism for triggering registration to global registries
+ based on the complete set of linked-to libraries.
+ - **third party**: A module representing an external dependency.
+ - **enable status**: A 4-way state to allow for "weak" and "strong" selection
+ or deselection of a module or group for building.
+
+## Principles
+
+The module system was designed with a number of principles in mind. These
+should be followed as much as possible when developing extensions as well.
+
+ - The minimum CMake version required by the module system should be as low
+ as possible to get the required features. For example, if a new feature is
+ available in 3.15 that improves core module functionality, that'd be a
+ reasonable reason to require it. But a bugfix in 3.10 that can be worked
+ around should not bump the minimum version. Currently CMake 3.8 is
+ expected to work, though various features (such as kits) are only
+ available with newer CMake versions.
+ - Build tree looks like the install tree. The layout of the build tree is set
+ up to mirror the layout of the install tree. This allows more code content
+ to be shared between build and install time.
+ - Convention over configuration. CMake conventions should be followed. Of
+ note, projects are assumed to be "well-behaved" including, but not limited
+ to:
+ - use of [`BUILD_SHARED_LIBS`][BUILD_SHARED_LIBS] to control shared vs.
+ static library compilation;
+ - use of [`GNUInstallDirs`][GNUInstallDirs]; and
+ - sensible defaults based on things like
+ [`CMAKE_PROJECT_NAME`][cmake-CMAKE_PROJECT_NAME] as set by the
+ [`project()`][cmake-project] function.
+ - Configuration through API. Where configuration is provided, instead of
+ using global state or "magic" variables, configuration should be provided
+ through parameters to the API functions provided. Concessions are made for
+ rarely-used functionality or where the API would be complicated to plumb
+ through the required information. These variables (which are typically
+ parameterized) are documented at the end of this document. Such variables
+ should be named so that it is unambiguous that they are for the module
+ system.
+ - Don't pollute the environment. Variables should be cleaned up at the end of
+ macros and functions should use variable names that don't conflict with the
+ caller environment (usually by prefixing with `_function_name_` or the
+ like).
+ - Relocatable installs. Install trees should not bake-in paths from the build
+ tree or build machine (at least by default). This makes it easier to create
+ packages from install trees instead of having to run a post-processing step
+ over it before it may be used for distributable packages.
+
+[BUILD_SHARED_LIBS]: https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html
+[GNUInstallDirs]: https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html
+[cmake-CMAKE_PROJECT_NAME]: https://cmake.org/cmake/help/latest/variable/CMAKE_PROJECT_NAME.html
+[cmake-project]: https://cmake.org/cmake/help/latest/command/project.html
+
+## Build process
+
+Building modules involves two phases. The first phase is called "scanning" and
+involves collecting all the information necessary for the second phase,
+"building". Scanning uses the {cmake:command}`vtk_module_scan` function to search the
+{ref}`vtk.module <module-parse-module>` files for metadata, gathers the set of modules
+to build and returns them to the caller. That list of modules is eventually passed to
+{cmake:command}`vtk_module_build` which sorts the modules for their build order and then
+builds each module in turn. This separation allows for scanning and building
+modules in different groups. For example, the main set of modules may be scanned
+to determine which of some internal set of modules are required by those which
+is then scanned separately with different options.
+
+Scanning should occur from the leaf-most module set and work its way inward to
+the lower levels. This is done so that modules in the lower level that are
+required higher up can be enabled gracefully. Builds should start at the lower
+level and move up the tree so that targets required by the higher groups exist
+when they are built.
+
+[vtk_module_scan]: https://vtk.org/doc/nightly/html/group__module.html#ga35849d7807a98a60e99e0a1c8ff54181
+
+## Modules
+
+Modules are described by {ref}`vtk.module <module-parse-module>` files. These files are "scanned" using
+the {cmake:command}`vtk_module_scan` function. They provide all the information necessary for
+the module system to:
+
+ - provide cache variables for selecting the module (e.g.,
+ `VTK_MODULE_ENABLE_ModuleName`);
+ - construct the dependency tree to automatically enable or disable modules
+ based on whether it is built or not;
+ - provide module-level metadata (such as exclusion from any wrapping and
+ marking modules as third party)
+
+The {ref}`vtk.module <module-parse-module>` files are read and "parsed", but not executed directly. This
+ensures that the module files do not contain any procedural CMake code. The
+files may contain comments starting with `#` like CMake code. They may either
+be passed manually to {cmake:command}`vtk_module_scan` or discovered by using the
+{cmake:command}`vtk_module_find_modules` convenience function.
+
+The most important (and only required) parameter is the `NAME` of a module.
+This is used as the target name in CMake and is how the module's target should
+be referred to in all CMake code, inside the build and from the
+[`find_package`][cmake-find_package] which provides the module. To change the
+name of the compiled artifact (library or executable), the `LIBRARY_NAME`
+argument may be used.
+
+It is highly recommended to provide a `DESCRIPTION` for the module. This is
+added to the documentation for the cache variable so that the user has more than
+just the module name to know what the module's purpose is.
+
+Modules may also belong to groups which are created implicitly by adding
+modules to the same-named group. Groups are listed under the `GROUPS` argument
+and are checked in order for a non-default setting to use.
+
+A module may be hidden by using the `CONDITION` argument. The values passed to
+this field is added into a CMake `if` statement and checked for validity (all
+quoting is passed along verbatim). If the condition evaluates to `FALSE`, the
+module is treated as if it did not exist at all.
+
+[cmake-find_package]: https://cmake.org/cmake/help/latest/command/find_package.html
+
+### Module metadata
+
+A number of pieces of metadata are considered important enough to indicate them
+at the module level. These are used for managing slightly different workflows
+for modules which have these properties.
+
+ - `EXCLUDE_WRAP`: This marks the module with a flag that all language wrapping
+ facilities should use to know that this module is not meant for wrapping in
+ any language. Usually this is for modules containing user interface classes,
+ low-level functionality, or logic that is language specific.
+ - `IMPLEMENTABLE` and `IMPLEMENTS`: These are used by the
+ [autoinit](#autoinit) functionality to trigger the static factory
+ registration calls. A module which is listed under an `IMPLEMENTS` list must
+ be marked as `IMPLEMENTABLE` itself.
+ - `THIRD_PARTY`: Indicates that the module represents a third party
+ dependency. It may be internal or external to the source tree, but may be
+ used as an additional configuration point if necessary. These modules are
+ implicitly `EXCLUDE_WRAP`, not `IMPLEMENTABLE` and do not `IMPLEMENTS` any
+ module.
+
+### Enabling modules for build
+
+Modules are enabled in a number of ways. These ways allow for project control
+and user control of which modules should be built or not. There are 4 states for
+controlling a module's {ref}`enable status <module-enable-status>`
+as well as a `DEFAULT`
+setting which is used to allow for other mechanisms to select the enable status:
+
+ - `YES`: The module must be built.
+ - `NO`: The module must not be built. If a `YES` module has a `NO` module in
+ its dependency tree, an error is raised.
+ - `WANT`: The module should be built. It will not be built, however, if it
+ depends on a `NO` module.
+ - `DONT_WANT`: The module doesn't need to be built. It will be built if a
+ `YES` or `WANT` module depends on it.
+ - `DEFAULT`: Look at other metadata to determine the status.
+
+The first check for modules are via the `REQUEST_MODULES` and `REJECT_MODULES`
+arguments to the `vtk_module_scan` function. Modules passed to
+`REQUEST_MODULES` are treated as if they use `YES` and `REJECT_MODULES` as if
+they use `NO`. A module may not be passed to both arguments. Modules selected
+in this way do not have CMake cache variables exposed for them (since it is
+assumed they are selected via some other mechanism outside the module system).
+
+The next selector is the `VTK_MODULE_ENABLE_` variable for the module. This is
+added to the cache and defaults to `DEFAULT`. Assuming `HIDE_MODULES_FROM_CACHE`
+is not set to `ON`, this setting is exposed in the cache and allows users to
+change the status of modules not handled via the `REQUEST_MODULES` and
+`REJECT_MODULES` mechanism.
+
+If a module is still selected as `DEFAULT`, the list of `GROUPS` it is a member
+of is used. In order, each group is looked at for a non-`DEFAULT` value. If so,
+its value is used for the module. Groups also default to using `DEFAULT` for
+their setting, but a project may set the `_vtk_module_group_default_${group}`
+variable to change this default value.
+
+After all of the above logic, if a module is still marked as `DEFAULT`, the
+`WANT_BY_DEFAULT` argument to {cmake:command}`vtk_module_scan` is used to determine whether
+it is treated as a `WANT` or `DONT_WANT` request.
+
+Now that all modules have a non-`DEFAULT` enable setting, the set of modules and
+kits that are available may be determined by traversing the dependency tree of
+the modules.
+
+### Dependencies
+
+Modules have three types of dependencies:
+
+ - `DEPENDS`: These are dependencies which must be available and are
+ transitively provided to modules depending on this module. The API of the
+ module may be affected by changes in these modules. This includes, but is
+ not limited to, classes in this module inherit or expose classes from the
+ dependent modules.
+ - `PRIVATE_DEPENDS`: Dependencies which are only used in the implementation
+ details of the module. The API of the module is not affected by changes in
+ these modules.
+ - `OPTIONAL_DEPENDS`: Dependencies which will be used if available, but the
+ implementation can cope with their absence. These are always treated as
+ `PRIVATE_DEPENDS` if they are available.
+
+Modules which are listed in `DEPENDS` or `PRIVATE_DEPENDS` are always available
+to the module and can be assumed to exist if the module is being built. Modules
+listed in `OPTIONAL_DEPENDS` cannot be assumed to exist. In CMake code, a
+`TARGET optional_depend` condition may be used to detect whether it is available
+or not. The module system will add a `VTK_MODULE_ENABLE_${module}` compilation
+definition set to either `0` or `1` if it is available for use in the module's
+code. This flag is made preprocessor-safe by replacing any `::` in the module
+name with `_`. So an optional dependency on `Namespace::Target` will use a flag
+named `VTK_MODULE_ENABLE_Namespace_Target`.
+
+At this stage, the dependency tree for all scanned modules is traversed, marking
+dependencies of `YES` modules as those that should be built, marking modules
+depending on `NO` modules as not to be built (and triggering an error if a
+conflict is found). Any `WANT` modules that have not been found in the trees of
+`YES` or `NO` modules are then enabled with their dependencies.
+
+There is a script to help figuring out dependencies when building your own modules
+or VTK-dependant code (*.cxx, *.h) in order to generate a [`find_package`][cmake-find_package]
+command. The required json argument is only available in a build tree though.
+
+`Utilities/Maintenance/FindNeededModules.py -s /path/to/sources -j path/to/vtk_build/modules.json`
+
+### Testing
+
+There is some support for testing in the module system, but it is not as
+comprehensive as the build side. This is because testing infrastructure and
+strategies vary wildly between projects. Rather than trying to handle the
+minimum baseline of any plausible testing infrastructure or framework, the
+module system merely handles dependency management for testing and entering a
+subdirectory with the tests.
+
+Modules may have `TEST_DEPENDS` and `TEST_OPTIONAL_DEPENDS` lists provided as
+well. These modules are required or optionally used by the testing code for the
+module.
+
+When scanning, the `ENABLE_TESTS` argument may be set to `ON`, `OFF`, `WANT`
+(the default), or `DEFAULT`. Modules which appear in `TEST_DEPENDS` for the
+module are affected by this setting.
+
+ - `ON`: Modules required for testing are treated as required. Tests will be
+ enabled.
+ - `OFF`: Tests will not be enabled.
+ - `WANT`: If possible, `TEST_DEPENDS` modules will also be enabled if they are
+ not disabled in some other way.
+ - `DEFAULT`: Check when tests are checked whether all of `TEST_DEPENDS` are
+ available. If they are, enable testing for the module, otherwise skip it.
+
+The only guarantee for testing provided is that all modules in the
+`TEST_DEPENDS` will be available before the testing is added and
+`TEST_OPTIONAL_DEPENDS` are available if they'd be available at all (i.e., they
+won't be made available later).
+
+Modules may also have `TEST_LABELS` set to ease labeling all tests for the
+module. The module system itself does nothing with this other than set a global
+property with the value. It is up to any test infrastructure used within the
+module's CMake code to make use of the value.
+
+The tests for a module are expected to live in a subdirectory of the module code
+itself. The name of this directory is given by the `TEST_DIRECTORY_NAME`
+argument to the {cmake:command}`vtk_module_build` function. If the directory is available and
+the module's testing is enabled, the module system will
+[`add_subdirectory`][cmake-add_subdirectory] this directory at the appropriate
+time. This is decoupled so that testing code can depend on modules that depend
+on the module that is being tested and the same `TARGET ${dependency}` check can
+be used for optional module dependencies.
+
+[cmake-add_subdirectory]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html
+
+## Building modules
+
+After scanning is complete, {cmake:command}`vtk_module_scan` returns a list of modules and
+kits to build in the variables given by the `PROVIDES_MODULES` and
+`PROVIDES_KITS` arguments to it. It also provides lists of modules that were
+found during scanning that were not scanned by that call. These are given back
+in the variables passed to the `UNRECOGNIZED_MODULES` and `REQUIRES_MODULES`
+variables.
+
+The `UNRECOGNIZED_MODULES` list contains modules passed to `REQUIRES_MODULES`
+and `REJECT_MODULES` that were not found during the scan. This typically
+indicates that the values passed to those arguments were not constructed
+properly. However, it may also mean that they should be passed on to further
+scans if they may be found elsewhere. Callers should handle the variable as
+necessary for their use case.
+
+The `REQUIRES_MODULES` are modules that were named as dependencies of the
+scanned modules and need to be provided in some way before building the provided
+modules (the build step will require that they exist when it tries to build the
+modules which required them). These can be passed on to future
+`REQUIRES_MODULES` arguments in future scans or used to error out depending on
+the use case of the caller.
+
+When using {cmake:command}`vtk_module_build`, the `PROVIDES_MODULES` and `PROVIDES_KITS` from
+a single scan should be passed together. Multiple scans may be built together as
+well if they all use the same build parameters as each other.
+
+### Build-time parameters
+
+The {cmake:command}`vtk_module_build` function is where the decision to build with or without
+kits is decided through the `BUILD_WITH_KITS` option. Only if this is set will
+kits be built for this set of modules.
+
+The decision to default third party modules to using an external or internal
+copy (where such a decision is possible) is done using the `USE_EXTERNAL`
+argument.
+
+Where build artifacts end up in the build tree are left to CMake's typical
+variables for controlling these locations:
+
+ - [`CMAKE_ARCHIVE_OUTPUT_DIRECTORY`][cmake-CMAKE_ARCHIVE_OUTPUT_DIRECTORY]
+ - [`CMAKE_LIBRARY_OUTPUT_DIRECTORY`][cmake-CMAKE_LIBRARY_OUTPUT_DIRECTORY]
+ - [`CMAKE_RUNTIME_OUTPUT_DIRECTORY`][cmake-CMAKE_RUNTIME_OUTPUT_DIRECTORY]
+
+The defaults for these place outputs into the binary directory where the targets
+were added. The module system will set these to be sensible for itself if they
+are not already set, but it is recommended to set these at the top-level so that
+targets not built under {cmake:command}`vtk_module_build` also end up at a sensible location.
+
+[cmake-CMAKE_ARCHIVE_OUTPUT_DIRECTORY]: https://cmake.org/cmake/help/latest/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.html
+[cmake-CMAKE_LIBRARY_OUTPUT_DIRECTORY]: https://cmake.org/cmake/help/latest/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.html
+[cmake-CMAKE_RUNTIME_OUTPUT_DIRECTORY]: https://cmake.org/cmake/help/latest/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.html
+
+### Library parameters
+
+When building libraries, it is sometimes useful to have top-level control of
+library metadata. For example, VTK suffixes its library filenames with a version
+number. The variables that control this include:
+
+ - `LIBRARY_NAME_SUFFIX`: If non-empty, all libraries and executable names will
+ be suffixed with this value prefixed with a hyphen (e.g., a suffix of `foo`
+ will make `Namespace::Target`'s library be named `Target-foo` or, if the
+ module sets its `LIBRARY_NAME` to `nsTarget`, `nsTarget-foo`).
+ - `VERSION`: Controls the [`VERSION`][cmake-VERSION] property for all library
+ modules.
+ - `SOVERSION`: Controls the [`SOVERSION`][cmake-SOVERSION] property for all
+ library modules.
+
+[cmake-VERSION]: https://cmake.org/cmake/help/latest/prop_tgt/VERSION.html
+[cmake-SOVERSION]: https://cmake.org/cmake/help/latest/prop_tgt/SOVERSION.html
+
+### Installation support
+
+{cmake:command}`vtk_module_build` also offers arguments to aid in installing module
+artifacts. These include destinations for pieces that are installed, CMake
+packaging controls, and components to use for the installations.
+
+A number of destinations control arguments are provided:
+
+ - `ARCHIVE_DESTINATION`
+ - `HEADERS_DESTINATION`
+ - `LIBRARY_DESTINATION`
+ - `RUNTIME_DESTINATION`
+ - `CMAKE_DESTINATION`
+ - `LICENSE_DESTINATION`
+ - `HIERARCHY_DESTINATION`
+
+See the API documentation for default values for each which are based on
+[`GNUInstallDirs`][GNUInstallDirs] variables. Note that all installation
+destinations are expected to be relative paths. This is because the conveniences
+provided by the module system are all assumed to be installed to a single prefix
+([`CMAKE_INSTALL_PREFIX`][cmake-CMAKE_INSTALL_PREFIX]) and placed underneath it.
+
+Suppression of header installation is provided via the `INSTALL_HEADERS`
+argument to {cmake:command}`vtk_module_build`. Setting this to `OFF` will suppress the
+installation of:
+
+ - headers
+ - CMake package files
+ - hierarchy files (since their use requires headers)
+
+Basically, suppression of headers means that SDK components for the built
+modules are not available in the install tree.
+
+Components for the installation are provided via the `HEADERS_COMPONENT` and
+`TARGETS_COMPONENT` arguments. The former is used for SDK bits and the latter
+for runtime bits (libraries, executables, etc.).
+
+For CMake package installation, the `PACKAGE` and `INSTALL_EXPORT` arguments are
+available. The former controls the names used by the CMake files created by the
+module system while the former is the export set to use for the member modules
+when creating those CMake files. Non-module targets may also exist in this
+export set when {cmake:command}`vtk_module_build` is called, but the export set is considered
+"closed" afterwards since it has already been exported (if `INSTALL_HEADERS` is
+true).
+
+[cmake-CMAKE_INSTALL_PREFIX]: https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html
+
+### Test data information
+
+The directory that is looked for in each module is specified by using the
+`TEST_DIRECTORY_NAME` argument. If it is set to the value of `NONE`, no testing
+directories will be searched for. It defaults to `Testing` due to VTK's
+conventions.
+
+The module system, due to VTK's usage of it, has convenience parameters for
+controlling the [`ExternalData`][ExternalData] module that is available to
+testing infrastructure. These include:
+
+ - `TEST_DATA_TARGET`: The data target to use for tests.
+ - `TEST_INPUT_DATA_DIRECTORY`: Where `ExternalData` should look for data
+ files.
+ - `TEST_OUTPUT_DATA_DIRECTORY`: Where `ExternalData` should place the
+ downloaded data files.
+ - `TEST_OUTPUT_DIRECTORY`: Where tests should place output files.
+
+Each is provided in the testing subdirectory as `_vtk_build_${name}`, so the
+`TEST_DATA_TARGET` argument is available as `_vtk_build_TEST_DATA_TARGET`.
+
+[ExternalData]: https://cmake.org/cmake/help/latest/module/ExternalData.html
+
+## Building a module
+
+Building a module is basically the same as a normal CMake library or executable,
+but is wrapped to use arguments to facilitate wrapping, exporting, and
+installation of the tools as well.
+
+There are two main functions provided for this:
+
+ - {cmake:command}`vtk_module_add_module`
+ - {cmake:command}`vtk_module_add_executable`
+
+The former creates a library for the module being built while the latter can
+create an executable for the module itself or create utility executable
+associated with the module. The module system requires that the `CMakeLists.txt`
+for a module create a target with the name of the module. In the case of
+`INTERFACE` modules, it suffices to create the module manually in many cases.
+
+### Libraries
+
+Most modules end up being libraries that can be linked against by other
+libraries. Due to cross-platform support generally being a good thing, the
+`EXPORT_MACRO_PREFIX` argument is provided to specify the prefix for macro names
+to be used by [`GenerateExportHeader`][GenerateExportHeader]. By default, the
+`LIBRARY_NAME` for the module is transformed to uppercase to make the prefix.
+
+Some modules may need to add additional information to the library name that
+will be used that is not statically know and depends on other environmental
+settings. The `LIBRARY_NAME_SUFFIX` may be specified to add an additional suffix
+to the `LIBRARY_NAME` for the module. The {cmake:command}`vtk_module_build`
+`LIBRARY_NAME_SUFFIX` argument value will be appended to this name as well.
+
+Normally, libraries are built according to the
+[`BUILD_SHARED_LIBS`][BUILD_SHARED_LIBS] variable, however, some modules may
+need to be built statically all the time. The `FORCE_STATIC` parameter exists
+for this purpose. This is generally only necessary if the module is in some
+other must-be-static library's dependency tree (which may happen for a number of
+reasons). It is not an escape hatch for general usage; it is there because use
+cases which only support static libraries (even in a shared build) exist.
+
+If a library module is part of a kit and it is being built via the
+{cmake:command}`vtk_module_build` `BUILD_WITH_KITS` argument, it will be built as an
+[`OBJECT`][cmake-OBJECT] library and the kit machinery in {cmake:command}`vtk_module_build`
+will create the resulting kit library artifact.
+
+Header-only modules must pass `HEADER_ONLY` to create an `INTERFACE` library
+instead of expecting a linkable artifact.
+
+```{note}
+`HEADER_ONLY` modules which are part of kits is currently untested. This
+should be supported, but might not work at the moment.
```
+
+[cmake-OBJECT]: https://cmake.org/cmake/help/latest/command/add_library.html
+[GenerateExportHeader]: https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html
+
+#### Source listing
+
+Instead of using CMake's "all sources in a single list" pattern for
+`add_library`, {cmake:command}`vtk_module_add_module` classifies its source files explicitly:
+
+ - `SOURCES`
+ - `HEADERS`
+ - `TEMPLATES`
+
+The `HEADERS` and `TEMPLATES` are installed into the `HEADERS_DESTINATION`
+specified to {cmake:command}`vtk_module_build` and may be added to a subdirectory of this
+destination by using the `HEADERS_SUBDIR` argument. Note that the structure of
+the header paths passed is ignored. If more structure is required from the
+installed header layout, {cmake:command}`vtk_module_install_headers` should be used.
+
+Files passed via `HEADERS` are treated as the API interface to the code of the
+module and are added to properties so that [language wrappers](#wrapping) can
+discover the API of the module.
+
+```{note}
+Only headers passed via `HEADERS` are eligible for wrapping; those
+installed via {cmake:command}`vtk_module_install_headers` are not. This is a known limitation
+at the moment.
+```
+
+There are also private variations for `HEADERS` and `TEMPLATES` named
+`PRIVATE_HEADERS` and `PRIVATE_TEMPLATES` respectively. These are never
+installed nor exposed to wrapping mechanisms.
+
+There are also a couple of convenience parameters that use VTK's file naming
+conventions to ease usage. These include:
+
+ - `CLASSES`: For each value `<class>`, adds `<class>.cxx` to `SOURCES` and
+ `<class>.h` to `HEADERS`.
+ - `TEMPLATE_CLASSES`: For each value `<class>`, adds `<class>.txx` to
+ `TEMPLATES` and `<class>.h` to `HEADERS`.
+ - `PRIVATE_CLASSES`: For each value `<class>`, adds `<class>.cxx` to `SOURCES`
+ and `<class>.h` to `PRIVATE_HEADERS`.
+ - `PRIVATE_TEMPLATE_CLASSES`: For each value `<class>`, adds `<class>.txx` to
+ `PRIVATE_TEMPLATES` and `<class>.h` to `PRIVATE_HEADERS`.
+
+### Executables
+
+Executables may be created using {cmake:command}`vtk_module_add_executable`. The first
+argument is the name of the executable to build. Since the scanning phase does
+not know what kind of target will be created for each module (and it may change
+based on other configuration values), an executable module which claims it is
+part of a kit raises an error since this is not possible to do.
+
+For modules that are executables using this function, the metadata from the
+module information is used to set the relevant properties. The module
+dependencies are also automatically linked in the same way as a library module
+would do so.
+
+For utility executables, `NO_INSTALL` may be passed to keep it within the build
+tree. It will not be available to consumers of the project. If the name of the
+executable is different from the target name, `BASENAME` may be used to change
+the executable's name.
+
+### Module APIs
+
+All of CMake's `target_` function calls have {ref}`analogues <module-target-functions>` for
+modules. This is primarily due to the kits feature which causes the target name
+created by the module system that is required to use the `target_` functions
+dependent on whether the module is a member of a kit and kits are being built.
+The CMake version of the function and the module API analogue (as well as
+differences, if any) is:
+
+ - [set_target_properties][cmake-set_target_properties] becomes
+ {cmake:command}`vtk_module_set_properties`
+ - [set_property(TARGET)][cmake-set_property] becomes
+ {cmake:command}`vtk_module_set_property`
+ - [get_property(TARGET)][cmake-get_property] becomes
+ {cmake:command}`vtk_module_get_property`
+ - [add_dependencies][cmake-add_dependencies] becomes {cmake:command}`vtk_module_depend`
+ - [target_include_directories][cmake-target_include_directories] becomes
+ {cmake:command}`vtk_module_include`
+ - [target_compile_definitions][cmake-target_compile_definitions] becomes
+ {cmake:command}`vtk_module_definitions`
+ - [target_compile_options][cmake-target_compile_options] becomes
+ {cmake:command}`vtk_module_compile_options`
+ - [target_compile_features][cmake-target_compile_features] becomes
+ {cmake:command}`vtk_module_compile_features`
+ - [target_link_libraries][cmake-target_link_libraries] becomes
+ {cmake:command}`vtk_module_link`: When kits are enabled, any `PRIVATE` links are
+ forwarded to the kit itself. This necessitates making all of these targets
+ globally scoped rather than locally scoped.
+ - [target_link_options][cmake-target_link_options] becomes
+ {cmake:command}`vtk_module_link_options`
+
+[cmake-set_target_properties]: https://cmake.org/cmake/help/latest/command/set_target_properties.html
+[cmake-set_property]: https://cmake.org/cmake/help/latest/command/set_property.html
+[cmake-get_property]: https://cmake.org/cmake/help/latest/command/get_property.html
+[cmake-add_dependencies]: https://cmake.org/cmake/help/latest/command/add_dependencies.html
+[cmake-target_include_directories]: https://cmake.org/cmake/help/latest/command/target_include_directories.html
+[cmake-target_compile_definitions]: https://cmake.org/cmake/help/latest/command/target_compile_definitions.html
+[cmake-target_compile_options]: https://cmake.org/cmake/help/latest/command/target_compile_options.html
+[cmake-target_compile_features]: https://cmake.org/cmake/help/latest/command/target_compile_features.html
+[cmake-target_link_libraries]: https://cmake.org/cmake/help/latest/command/target_link_libraries.html
+[cmake-target_link_options]: https://cmake.org/cmake/help/latest/command/target_link_options.html
+
+## Packaging support
+
+Getting installed packages to work for CMake is, unfortunately, not trivial. The
+module system provides some support for helping with this, but it does place
+some extra constraints on the project so that some assumptions that vastly
+simplify the process can be made.
+
+### Assumptions
+
+The main assumption is that all modules passed to a single {cmake:command}`vtk_module_build`
+have the same CMake namespace (the part up to and including the `::`, if any,
+in a module name. For exporting dependencies, that namespace matches the
+`PACKAGE` argument for {cmake:command}`vtk_module_build`. These are done so that the
+generated code can use
+[`CMAKE_FIND_PACKAGE_NAME`][cmake-CMAKE_FIND_PACKAGE_NAME] variable can be
+used to discover information about the package that is being found.
+
+The package support also assumes that all modules may be queried using
+`COMPONENTS` and `OPTIONAL_COMPONENTS` and that the component name for a module
+corresponds to the name of a module without the namespace.
+
+These rules basically mean that a module named `Namespace::Target` will be found
+using `find_package(Namespace)`, that `COMPONENTS Target` may be passed to
+ensure that that module exists, and `OPTIONAL_COMPONENTS Target` may be passed
+to allow the component to not exist while not failing the main
+[`find_package`][cmake-find_package] call.
+
+[cmake-CMAKE_FIND_PACKAGE_NAME]: https://cmake.org/cmake/help/latest/variable/CMAKE_FIND_PACKAGE_NAME.html
+
+### Creating a full package
+
+The module system provides no support for the top-level file that is used by
+[`find_package`][cmake-find_package]. This is because this logic is highly
+project-specific and hard to generalize in a useful way. Instead, files are
+generated which should be included from the main file.
+
+Here, the list of files generated are based on the `PACKAGE` argument passed to
+{cmake:command}`vtk_module_build`:
+
+ - `<PACKAGE>-targets.cmake`: The CMake-generated export file for the targets
+ in the `INSTALL_EXPORT`.
+ - `<PACKAGE>-vtk-module-properties.cmake`: Properties for the targets exported
+ into the build.
+
+The module properties file must be included after the targets file so that they
+exist when it tries to add properties to the imported targets.
+
+### External dependencies
+
+Since the module system is heavily skewed towards using imported targets, these
+targets show up by name in the [`find_package`][cmake-find_package] of the
+project as well. This means that these external projects need to be found to
+recreate their imported targets at that time. To this end, there is the
+{cmake:command}`vtk_module_export_find_packages` function. This function writes a file named
+according to its `FILE_NAME` argument and place it in the build and install
+trees according to its `CMAKE_DESTINATION` argument.
+
+This file will be populated with logic to determine whether third party packages
+found using {cmake:command}`vtk_module_find_package` are required during the
+[`find_package`][cmake-find_package] of the package or not. It will forward
+`REQUIRED` and `QUIET` parameters to other [`find_package`][cmake-find_package]
+calls as necessary based on the `REQUIRED` and `QUIET` flags for the package
+and whether that call is involved in a non-optional `COMPONENT` (a
+component-less [`find_package`][cmake-find_package] call is assumed to mean
+"all components").
+
+This file should be included after the `<PACKAGE>-vtk-module-properties.cmake`
+file generated by the {cmake:command}`vtk_module_build` call so that it can use the module
+dependency information set via that file.
+
+After this file is included, for each component that it checks, it will set
+`${CMAKE_FIND_PACKAGE_NAME}_<component>_FOUND` to 0 if it is not valid and
+append a reason to `${CMAKE_FIND_PACKAGE_NAME}_<component>_NOT_FOUND_MESSAGE`
+so that the package can collate the reason why things are not available.
+
+### Setting the `_FOUND` variable
+
+The module system does not currently help in determining the top-level
+`${CMAKE_FIND_PACKAGE_NAME}_FOUND` variable based on the results of the
+components that were requested and the status of dependent packages. This may be
+provided at some point, but there has not currently been enough experience to
+determine what patterns are available for factoring it out as a utility
+function.
+
+The general pattern should be to go through the list of components requested,
+determine whether targets for those components exist. Then for each found
+component, use the module dependency information to ensure that all targets in
+the dependency trees are found (propagating not-found statuses through the
+dependency tree). The `${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE` should be
+built up based on the reasons the [`find_package`][cmake-find_package] call did
+not work based on these discoveries.
+
+This is the process for modules in a package, but packages may contain
+non-module components, and it is hard for the module system to provide support
+for them, so they are not attempted. See the CMake documentation for more
+details about [creating a package configuration][cmake-create-package-config].
+
+[cmake-create-package-config]: https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html#creating-a-package-configuration-file
+
+## Advanced topics
+
+There are a number of advanced features provided by the module system that are
+not normally required in a simple project.
+
+### Kits
+
+Kits are described in {ref}`vtk.kit <module-parse-kit>` files which act much like {ref}`vtk.module <module-parse-module>`
+files. However, they only have `NAME`, `LIBRARY_NAME`, and `DESCRIPTION` fields.
+These all act just like they do in the `vtk.module` context. These files may
+either be passed manually to {cmake:command}`vtk_module_scan` or discovered by using the
+{cmake:command}`vtk_module_find_kits` convenience function.
+
+Before a module may be a member of a kit, a {ref}`vtk.kit <module-parse-kit>` must declare it and be
+scanned at the same time. This means that kits may only contain modules that are
+scanned with them and cannot be extended later nor may kits be made of modules
+that they do not know about.
+
+#### Requirements
+
+In order to actually use kits, CMake 3.12 is necessary in order to do the
+[`OBJECT`][cmake-OBJECT] library manipulations done behind the scenes to make it
+Just Work. 3.8 is still the minimum version for using a project that is built
+with kits however. This is only checked when kits are actually in use, so
+projects requiring older CMake versions as their minimum version may still
+provide kits so that users with newer CMake versions can use them.
+
+Kits create a single library on disk, but the usage requirements of the modules
+should still be the same (except for that which is inherently required to be
+different by combining libraries). So include directories, compile definitions,
+and other usage requirements should not leak from other modules that are members
+of the same kit.
+
+<a name="autoinit"></a>
+### Autoinit
+
+The module system supports a mechanism for triggering static code construction
+for modules which require it. This cannot be done through normal CMake usage
+requirements because the requirements are intersectional. For example, a module
+`F` having a factory where module `I` provides an implementation for it means
+that a target linking to both `F` and `I` needs to ensure that `I` registers its
+implementation to the factory code. There is no such support in CMake and due to
+the complexities and code generation involved with this support, it is unlikely
+to exist.
+
+Code which uses modules may call the {cmake:command}`vtk_module_autoinit` function to use
+this functionality. The list of modules passed to the function are used to
+compute the defines necessary to trigger the registration to factories when
+necessary.
+
+For details on the implementation of the autoinit system, please see
+{ref}`the relevant section <module-autoinit>` in the API documentation.
+
+<a name="wrapping"></a>
+### Wrapping
+
+VTK comes with support for wrapping its classes into other languages.
+Currently, VTK supports wrapping its classes for use in the Python and Java
+languages. In order to wrap a set of modules for a language, a separate
+function is used for each language.
+
+All languages read the headers of classes with a `__VTK_WRAP__` preprocessor
+definition defined. This may be used to hide methods or other details from the
+wrapping code if wanted.
+
+#### Python
+
+For Python, the {cmake:command}`vtk_module_wrap_python` function must be used. This function
+takes a list of modules in its `MODULES` argument and creates Python modules
+for use under the `PYTHON_PACKAGE` package. No `__init__.py` for this package
+is created automatically and must be provided in some other way.
+
+A target named by the `TARGET` argument is created and installed. This target
+may be linked to in order to be able to import static Python modules. In this
+case, a header and function named according to the basename of `TARGET` (e.g.,
+`VTK::PythonWrapped` has a basename of `PythonWrapped`) must be used. The
+header is named `<TARGET_BASENAME>.h` and the function which adds the wrapped
+modules to the static import table is `<void TARGET_BASENAME>_load()`. This
+function is also created in shared builds, but does nothing so that it may
+always be called in static or shared builds.
+
+The modules will be installed under the `MODULE_DESTINATION` given to the
+function into the `PYTHON_PACKAGE` directory needed for it. The
+{cmake:command}`vtk_module_python_default_destination` function is used to determine a
+default if one is not passed.
+
+The Python wrappers define a `__VTK_WRAP_PYTHON__` preprocessor definition when
+reading code which may be used to hide methods or other details from the Python
+wrapping code.
+
+#### Java
+
+For Java, the {cmake:command}`vtk_module_wrap_java` function must be used. This function
+creates Java sources for classes in the modules passed in its `MODULES`
+argument. The sources are written to a `JAVA_OUTPUT` directory. These then can
+be compiled by CMake normally.
+
+For this purpose, there are `<MODULE>Java` targets which contain a
+`_vtk_module_java_files` properties containing a list of `.java` sources
+generated for the given module. There is also a `<MODULE>Java-java-sources`
+target which may be depended upon if just the source generation needs to used
+in an [`add_dependencies`][cmake-add_dependencies] call.
+
+The Java wrappers define a `__VTK_WRAP_JAVA__` preprocessor definition when
+reading code which may be used to hide methods or other details from the Java
+wrapping code.
+
+#### Hierarchy files
+
+Hierarchy files are used by the language wrapper tools to know the class
+inheritance for classes within a module. Each module has a hierarchy file
+associated with it. The path to a module's hierarchy file is stored in its
+`hierarchy` module property.
+
+### Third party
+
+The module system has support for representing third party modules in its
+build. These may be built as part of the project or represented using other
+mechanisms (usually [`find_package`][cmake-find_package] and a set of imported
+targets from it).
+
+The primary API is {cmake:command}`vtk_module_third_party` which creates a
+`VTK_MODULE_USE_EXTERNAL_Namespace_Target` option for the module to switch
+between an internal and external source for the third party code. This value
+defaults to the setting of the `USE_EXTERNAL` argument for the calling
+{cmake:command}`vtk_module_build` function. Arguments passed under the `INTERNAL` and
+`EXTERNAL` arguments to this command are then passed on to
+{cmake:command}`vtk_module_third_party_internal` or {cmake:command}`vtk_module_third_party_external`,
+respectively, depending on the `VTK_MODULE_USE_EXTERNAL_Namespace_Target`
+option.
+
+Note that third party modules (marked as such by adding the `THIRD_PARTY`
+keyword to a `vtk.module` file) may not be part of a kit, be wrapped, or
+participate in autoinit.
+
+#### External third party modules
+
+External modules are found using CMake's [`find_package`][cmake-find_package]
+mechanism. In addition to the arguments supported by
+{cmake:command}`vtk_module_find_package` (except `PRIVATE`), information about the found
+package is used to construct a module target which represents the third party
+package. The preferred mechanism is to give a list of imported targets to the
+`LIBRARIES` argument. These will be added to the `INTERFACE` of the module and
+provide the third party package for use within the module system.
+
+If imported targets are not available (they really should be created if not),
+variable names may be passed to `INCLUDE_DIRS`, `LIBRARIES`, and `DEFINITIONS`
+to create the module interface.
+
+In addition, any variables which should be forwarded from the package to the
+rest of the build may be specified using the `USE_VARIABLES` argument.
+
+The `STANDARD_INCLUDE_DIRS` argument creates an include interface for the
+module target which includes the "standard" module include directories to.
+Basically, the source and binary directories of the module.
+
+#### Internal third party modules
+
+Internal modules are those that may be built as part of the build. These should
+ideally specify a set of `LICENSE_FILES` indicating the license status of the
+third party code. These files will be installed along with the third party
+package to aid in any licensing requirements of the code. It is also
+recommended to set the `VERSION` argument so that it is known what version of
+the code is provided at a glance.
+
+By default, the `LIBRARY_NAME` of the module is used as the name of the
+subdirectory to include, but this may be changed by using the `SUBDIRECTORY`
+argument.
+
+Header-only third party modules may be indicated by using the `HEADER_ONLY`
+argument. Modules which represent multiple libraries at once from a project may
+use the `INTERFACE` argument.
+
+The `STANDARD_INCLUDE_DIRS` argument creates an include interface for the
+module target which includes the "standard" module include directories to.
+Basically, the source and binary directories of the module. A subdirectory may
+be used by setting the `HEADERS_SUBDIR` option. It is implied for
+`HEADERS_ONLY` third party modules.
+
+After the subdirectory is added a target with the module's name must exist.
+However, a target is automatically created if it is `HEADERS_ONLY`.
+
+##### Properly shipping internal third party code
+
+There are many things that really should be done to ship internal third party
+code (also known as vendoring) properly. The issue is mainly that the internal
+code may conflict with other code bringing in another copy of the same package
+into a process. Most platforms do not behave well in this situation.
+
+In order to avoid conflicts at every level possible, a process called "name
+mangling" should be performed. A non-exhaustive list of name manglings that
+must be done to fully handle this case includes:
+
+ - moving headers to a subdirectory (to avoid compilations from finding
+ incompatible headers);
+ - changing the library name (to avoid DLL lookups from finding incompatible
+ copies); and
+ - mangling symbols (to avoid symbol lookup from confusing two copies in the
+ same process).
+
+Some projects may need further work like editing CMake APIs or the like to be
+mangled as well.
+
+Moving headers and changing library names is fairly straightforward by editing
+CMake code. Mangling symbols usually involves creating a header which has a
+`#define` for each public symbol to change its name at runtime to be distinct
+from another copy that may end up existing in the same process from another
+project.
+
+Typically, a header needs to be created at the module level which hides the
+differences between third party code which may or may not be provided by an
+external package. In this case, it is recommended that code using the third
+party module use unmangled names and let the module interface and mangling
+headers handle the mangling at that level.
+
+### Debugging
+
+The module system can output debugging information about its inner workings by
+using the `_vtk_module_log` variable. This variable is a list of "domains" to
+log about, or the special `ALL` value causes all domains to log output. The
+following domains are used in the internals of the module system:
+
+ - `kit`: discovery and membership of kits
+ - `module`: discovery and `CONDITION` results of modules
+ - `enable`: resolution of the enable status of modules
+ - `provide`: determination of module provision
+ - `building`: when building a module occurs
+ - `testing`: missing test dependencies
+
+It is encouraged that projects expose user-friendly flags to control logging
+rather than exposing `_vtk_module_log` directly.
+
+### Control variables
+
+These variables do not follow the API convention and are used if set:
+
+ - `_vtk_module_warnings`: If enabled, "strict" warnings are generated. These
+ are not strictly problems, but may be used as linting for improving usage of
+ the module system.
+ - `_vtk_module_log`: A list of "domains" to output debugging information.
+ - `_vtk_module_group_default_${group}`: used to set a non-`DEFAULT` default
+ for group settings.
+
+Some mechanisms use global properties instead:
+
+ - `_vtk_module_autoinit_include`: The file that needs to be included in order
+ to make the `VTK_MODULE_AUTOINIT` symbol available for use in the
+ [autoinit](#autoinit) support.
+
+### SPDX files generation
+
+The generation of VTK module SPDX files relies on three components:
+
+ - SPDX arguments in {cmake:command}`vtk_module_build`
+ - SPDX arguments in each {ref}`vtk.module <module-parse-module>`
+ - SPDX Tags in the [sources files](#source-listing)
+
+SPDX files are named after `<ModuleName>.spdx` and are generated for
+all VTK modules.
+
+Generated SPDX files are based on the [SPDX 2.2 specification](https://spdx.dev/specifications/).
+
+If some information is missing, VTK will warn during configuration or during build
+but the SPDX file will still be generated with unknown fields being attributed a
+`NOASSERTION` or other default value.
+
+The collected license identifiers are joined together using `AND` keyword.
+
+Similarly all collected copyright texts are joined using a new line.
+
+#### SPDX arguments in `vtk_module_build`
+
+Support for SPDX file generation requires to specifiy the following
+{cmake:command}`vtk_module_build` arguments:
+
+- `GENERATE_SPDX`
+- `SPDX_DOCUMENT_NAMESPACE`
+- `SPDX_DOWNLOAD_LOCATION`
+
+`GENERATE_SPDX` is used to enable the generation and install of SPDX file for
+each modules. Set this to `ON` to enable it.
+
+`SPDX_DOCUMENT_NAMESPACE` is used as a basename for the `DocumentNamespace`
+SPDX field. The name of the module will simply be appended to the basename.
+If not provided, `https://vtk.org/spdx` will be used. This is the value VTK
+project uses as well. Note that the namespace does not need to be an actual
+website URL, but just a unique Uniform Resource Identifier (URI).
+
+:::{caution}
+If VTK decide to host SPDX files in the future, the namespace in use for the
+VTK SPDX files may change accordingly.
+:::
+
+`SPDX_DOWNLOAD_LOCATION` is used as a basename for the `PackageDownloadLocation`
+when not provided at module level. The relative path to the module will simply
+be appended in order to generate the actual `PackageDownloadLocation` SPDX field.
+If not provided at module or in {cmake:command}`vtk_module_build`, `NOASSERTION`
+will be used.
+
+#### SPDX arguments in `vtk.module`
+
+Defining these three arguments in {ref}`vtk.module <module-parse-module>` is required:
+ - `SPDX_LICENSE_IDENTIFIER`
+ - `SPDX_COPYRIGHT_TEXT`
+ - `SPDX_DOWNLOAD_LOCATION`
+
+`SPDX_LICENSE_IDENTIFIER` is an expected field corresponding to the `PackageLicenseDeclared`
+SPDX field that is considered as the global license for all files of the
+module that are not parsed during generation. This field is used to set
+the `PackageLicenseConcluded` SPDX field.
+
+:::{note}
+The SPDX generation system do not and cannot replace the `LICENSE_FILES` mechanism.
+Indeed, certains license (e.g Apache 2.0) requires additonal files (e.g `NOTICE`) to
+also be distributed.
+:::
+
+`SPDX_COPYRIGHT_TEXT` is an expected field that correspond to the copyright applying
+to all files that are not parsed during generation, it is used to generate `PackageCopyrightText`.
+
+`SPDX_DOWNLOAD_LOCATION` is a optional field for modules (see above for setting
+this in `vtk_module_build`) and expected field for [third parties](/developers_guide/git/thirdparty.md).
+If provided, it is used as is for the `PackageDownloadLocation` SPDX field.
+
+#### Custom license support
+
+If the VTK module contains a custom license that is not part of the [SPDX license list](https://spdx.org/licenses/)
+then adding a custom license may be needed.
+
+The SPDX generation system support to specify exactly one custom license by module, supplemental to standard licenses.
+The text of this license should be made available in a file and added to the module definition using `SPDX_CUSTOM_LICENSE_FILE`
+, the name of the license should be specified using `SPDX_CUSTOM_LICENSE_NAME` (eg: `LicenseName` and the `SPDX_LICENSE_IDENTIFIER` for this license
+should be `LicenseRef-` followed by the name (eg: `LicenseRef-licenseName`). See [this entry](/advanced/spdx_and_sbom.md#frequently-asked-questions) for more info.
+
+:::{note}
+If this custom license is to be added to VTK proper, it must be compatible with the BSD-3-CLAUSE license of VTK and
+not add more restriction to the code.
+:::
+
+#### SPDX Tags in the sources files
+
+For VTK modules (except the one declared as `THIRD_PARTY`), [sources files](#source-listing)
+are parsed for specific SPDX tags in a specific order.
+
+First `N` lines of with the the `SPDX-FileCopyrightText` tag, then one line with
+the `SPDX-License-Identifier` tag. Like this:
+
+```
+// SPDX-FileCopyrightText: Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
+// SPDX-FileCopyrightText: Copyright (c) Awesome contributor
+// SPDX-License-Identifier: BSD-3-CLAUSE
+```
+
+If a source file does not contain both `SPDX-FileCopyrightText` and `SPDX-License-Identifier`
+tags, a CMake warning is reported.
+
+TODO: It would be possible to add a dedicated tag to identify that a file should NOT be parsed for SPDX tags,
+but it is not needed yet.
+
+#### Limitations
+
+* Correctness of the `SPDX-FileCopyrightText` and `SPDX-License-Identifier` tags is not ensured. The value
+ will be used as is.
+
+* The generated SPDX files only include the [Package information][spdx-package-information]
+ section. This means that there are no [File information][spdx-file-information] sections
+ describing source files or build artifacts.
+
+* Third party source files are not parsed for SPDX tags.
+
+[spdx-package-information]: https://spdx.github.io/spdx-spec/v2.2.2/package-information/
+[spdx-file-information]: https://spdx.github.io/spdx-spec/v2.2.2/file-information/
+
+* Adding empty lines between `// SPDX-FileCopyrightText` and `// SPDX-License-Identifier`
+ tags is not supported.
+
+* Only comments starting with `//` are considered.
diff --git a/Documentation/docs/build_instructions/.gitignore b/Documentation/docs/build_instructions/.gitignore
deleted file mode 100644
index 9b2d8e9142744cb7dae0db0629fa228a01c1c8d0..0000000000000000000000000000000000000000
--- a/Documentation/docs/build_instructions/.gitignore
+++ /dev/null
@@ -1,2 +0,0 @@
-# generated by conf.py
-build_wasm_emscripten.md
diff --git a/Documentation/docs/build_instructions/build.md b/Documentation/docs/build_instructions/build.md
index 5ae7722cc3f15cf2f48126174517c2e5ca8a55e4..6edc8780a56495fa2733cbda7661d59cad9ffe45 100644
--- a/Documentation/docs/build_instructions/build.md
+++ b/Documentation/docs/build_instructions/build.md
@@ -1,2 +1,274 @@
-```{include} ../../dev/build.md
+# Building
+
+This page describes how to build and install VTK. It covers building for
+development, on both Unix-type systems (Linux, HP-UX, Solaris, macOS), and
+Windows. Note that Unix-like environments such as Cygwin and MinGW are not
+officially supported. However, patches to fix problems with these platforms
+will be considered for inclusion. It is recommended that users which require
+VTK to work on these platforms to submit nightly testing results for them.
+
+A full-featured build of VTK depends on several open source tools and libraries
+such as Python, Qt, CGNS, HDF5, etc. Some of these are included in the VTK
+source itself (e.g., HDF5), while others are expected to be present on the
+machine on which VTK is being built (e.g., Python, Qt).
+
+VTK supports all of the common generators supported by CMake. The Ninja,
+Makefiles, and Visual Studio generators are the most well-tested however.
+
+Note that VTK does not support in-source builds, so you must have a build tree
+that is not the source tree.
+
+## Obtaining the sources
+
+ There are two approaches:
+
+::::{tab-set}
+
+:::{tab-item} Release Download
+1. Download the source release `VTK-X.Y.Z.tar.gz` from https://vtk.org/download/.
+2. Create a folder for VTK.
+3. Extract the contents of the VTK folder in the downloaded archive to the subfolder called `source`
+:::
+
+:::{tab-item} Git Clone
+To obtain VTK's sources locally, clone the VTK repository using [Git][git].
+
+[git]: https://git-scm.org
+
+Open `Git Bash` on Windows or a terminal on Linux and macOS and
+execute the following:
+
+```sh
+mkdir -p ~/vtk
+git clone --recursive https://gitlab.kitware.com/vtk/vtk.git ~/vtk/source
```
+:::
+
+::::
+
+To use the latest features being developed or to make changes and
+contribute to VTK, download the source using **Git Clone**.
+
+## Prerequisites
+
+VTK only requires a few packages in order to build in general, however
+specific features may require additional packages to be provided to VTK's
+build configuration.
+
+Required:
+
+ * [CMake][cmake]
+ - Version 3.12 or newer, however, the latest version is always recommended.
+ If the system package management utilities do not offer cmake or if the offered version is too old
+ Precompiled binaries available on [CMake's download page][cmake-download].
+
+ * Supported compiler
+ - GCC 4.8 or newer
+ - Clang 3.3 or newer
+ - Apple Clang 7.0 (from Xcode 7.2.1) or newer
+ - Microsoft Visual Studio 2015 or newer
+ - Intel 14.0 or newer
+
+### Optional Additions
+
+- **ffmpeg**
+ When the ability to write `.avi` files is desired, and writing these files is
+ not supported by the OS, VTK can use the ffmpeg library. This is generally
+ true for Unix-like operating systems. Source code for ffmpeg can be obtained
+ from [the website][ffmpeg].
+
+- **MPI**
+ To run VTK in parallel, an [MPI][mpi] implementation is required. If an MPI
+ implementation that exploits special interconnect hardware is provided on your
+ system, we suggest using it for optimal performance. Otherwise, on Linux/Mac,
+ we suggest either [OpenMPI][openmpi] or [MPICH][mpich]. On Windows, [Microsoft
+ MPI][msmpi] is required.
+
+- **Python**
+ In order to use scripting, [Python][python] is required. The minimum supported version is **3.4**.
+ The instructions are using the system Python. On Ubuntu/Debian the required package is
+ `python3-dev`. If you use a different Python
+ implementation or a virtual environment make sure the environment you use is
+ activated. On Ubuntu/Debian the required package for creating virtual environments is
+ `python3-venv`.
+
+- **Qt5**
+ VTK uses Qt as its GUI library (if the relevant modules are enabled).
+ Precompiled binaries are available on [Qt's website][qt-download].
+ Note that on Windows, the compiler used for building VTK must match the
+ compiler version used to build Qt. Version **5.9** or newer is required.
+
+- **OSMesa**
+ Off-screen Mesa can be used as a software-renderer for running VTK on a server
+ without hardware OpenGL acceleration. This is usually available in system
+ packages on Linux. For example, the `libosmesa6-dev` package on Debian and
+ Ubuntu. However, for older machines, building a newer version of Mesa is
+ likely necessary for bug fixes and support. Its source and build instructions
+ can be found on [its website][mesa].
+
+[cmake]: https://cmake.org
+[cmake-download]: https://cmake.org/download
+[ffmpeg]: https://ffmpeg.org
+[mpi]: https://www.mcs.anl.gov/research/projects/mpi
+[mpich]: https://www.mpich.org
+[msmpi]: https://docs.microsoft.com/en-us/message-passing-interface/microsoft-mpi
+[openmpi]: https://www.open-mpi.org
+[python]: https://python.org
+[qt-download]: https://download.qt.io/official_releases/qt
+[mesa]: https://www.mesa3d.org
+
+## Creating the Build Environment
+
+::::{tab-set}
+
+:::{tab-item} Windows
+
+ * Install CMake
+
+ * Install [Visual Studio Community Edition][visual-studio]
+
+ * During installation select the "desktop development with C++" workload.
+
+ * Use "x64 Native Tools Command Prompt" for the installed Visual Studio
+ version to configure with CMake and to build with ninja.
+
+ * Get [ninja][ninja]. Unzip the binary and put it in `PATH`. Note that newer
+ Visual Studio releases come with a version of `ninja` already and should
+ already exist in `PATH` within the command prompt.
+
+[ninja]: https://ninja-build.org
+[visual-studio]: https://visualstudio.microsoft.com/vs
+
+:::
+
+:::{tab-item} Linux (Ubuntu/Debian)
+
+Install the following packages:
+
+```bash
+$ sudo apt install \
+build-essential \
+cmake \
+cmake-curses-gui \
+mesa-common-dev \
+mesa-utils \
+freeglut3-dev \
+ninja-build
+```
+:::
+
+:::{tab-item} macOS
+
+* Install CMake
+
+* Install XCode
+
+* Ensure XCode command line tools are installed:
+
+```bash
+xcode-select --install
+```
+:::
+
+::::
+
+```{note}
+`ninja` is a more efficient alternative to `Makefiles` or Visual Studio solution files. The
+speed increase is the most noticeable when doing incremental build.
+```
+
+## Configure
+
+In order to build, CMake requires two steps, configure and build. VTK itself
+does not support what are known as in-source builds, so the first step is to
+create a build directory.
+
+::::{tab-set}
+
+:::{tab-item} Windows (Ninja)
+
+Open "x64 Native Tools Command Prompt" for the installed Visual Studio:
+
+```sh
+ccmake -GNinja -S %HOMEPATH%\vtk\source -B %HOMEPATH%\vtk\build
+```
+
+Note that CMake GUI must also be launched from the "Native Tools Command Prompt".
+
+:::
+
+:::{tab-item} Windows (Visual Studio)
+
+Use CMake to generate a Visual Studio solution file (`.sln`).
+
+1. Open CMake GUI, either by typing `cmake-gui` on the command prompt or from the start-menu.
+2. Enter the source and build directories
+3. Click `[Configure]`
+4. You will now get a selection screen in which you can specify your "generator". Select the one you need.
+5. We are now presented with a few options that can be turned on or off as desired.
+6. Click `[Configure]` to apply the changes.
+7. Click `[Generate]`. This will populate the "build" sub-folder.
+8. Finally, click `[Open Project]` to open the generated solution in Visual Studio.
+
+:::
+
+:::{tab-item} Linux/macOS
+
+```sh
+mkdir -p ~/vtk/build
+cd ~/vtk/build
+ccmake -GNinja ../path/to/vtk/source
+```
+
+The parameter `-GNinja` may be skipped to use the default generator (e.g `Unix Makefiles`).
+:::
+
+::::
+
+```{admonition} **Missing dependencies**
+:class: warning
+
+CMake may not find all dependencies automatically in all cases. The steps
+needed to find any given package depends on the package itself.
+
+For general assistance, please see the documentation for
+[`find_package`'s search procedure][cmake-find_package-search] and
+[the relevant Find module][cmake-modules-find] (as available).
+
+[cmake-find_package-search]: https://cmake.org/cmake/help/latest/command/find_package.html#search-procedure
+[cmake-modules-find]: https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html#find-modules
+```
+:::{hint}
+Different features can be enabled/disabled by setting the [Build Settings](build_settings.md) during the configure stage.
+:::
+
+## Building
+
+To build VTK:
+
+::::{tab-set}
+
+:::{tab-item} Windows (Ninja)
+
+```sh
+cmake --build %HOMEPATH%\vtk\build --config Release
+```
+:::
+
+:::{tab-item} Windows (Visual Studio)
+
+Open the generated solution file.
+
+1. Set the configuration to "Release"
+
+2. On the menu bar, choose `Build`, and then choose `Build Solution`.
+:::
+
+:::{tab-item} Linux/macOS
+
+```sh
+cmake --build ~/vtk/build
+```
+:::
+
+::::
diff --git a/Documentation/docs/build_instructions/build_settings.md b/Documentation/docs/build_instructions/build_settings.md
index 9a48bdd67ac88fda3ae46b797b886fe3e7dfa39b..0e36e5cb69ddb3ae98fea0d013e20c12ece4d72a 100644
--- a/Documentation/docs/build_instructions/build_settings.md
+++ b/Documentation/docs/build_instructions/build_settings.md
@@ -1,2 +1,291 @@
-```{include} ../../dev/build_settings.md
+# Build Settings
+
+VTK has a number of settings available for its build. The common variables
+to modify include:
+
+ * `BUILD_SHARED_LIBS` (default `ON`): If set, shared libraries will be
+ built. This is usually what is wanted.
+ * `VTK_USE_CUDA` (default `OFF`): Whether [CUDA][cuda] support will be available or
+ not.
+ * `VTK_USE_MPI` (default `OFF`): Whether [MPI][mpi] support will be available or
+ not.
+ * `VTK_WRAP_PYTHON` (default `OFF`; requires `VTK_ENABLE_WRAPPING`): Whether
+ Python support will be available or not.
+
+Less common, but variables which may be of interest to some:
+
+ * `VTK_BUILD_EXAMPLES` (default `OFF`): If set, VTK's example code will be
+ added as tests to the VTK test suite.
+ * `VTK_ENABLE_LOGGING` (default `ON`): If set, enhanced logging will be
+ enabled.
+ * `VTK_LOGGING_TIME_PRECISION` (default `3`; requires `VTK_ENABLE_LOGGING`):
+ Change the precision of times output when `VTK_ENABLE_LOGGING` is on.
+ * `VTK_BUILD_TESTING` (default `OFF`): Whether to build tests or not. Valid
+ values are `OFF` (no testing), `WANT` (enable tests as possible), and `ON`
+ (enable all tests; may error out if features otherwise disabled are
+ required by test code).
+ * `VTK_ENABLE_KITS` (default `OFF`; requires `BUILD_SHARED_LIBS`): Compile
+ VTK into a smaller set of libraries. Can be useful on platforms where VTK
+ takes a long time to launch due to expensive disk access.
+ * `VTK_ENABLE_WRAPPING` (default `ON`): Whether any wrapping support will be
+ available or not.
+ * `VTK_WRAP_JAVA` (default `OFF`; requires `VTK_ENABLE_WRAPPING`):
+ Whether Java support will be available or not.
+ * `VTK_SMP_IMPLEMENTATION_TYPE` (default `Sequential`): Set which SMPTools
+ will be implemented by default. Must be either `Sequential`, `STDThread`,
+ `OpenMP` or `TBB`. The backend can be changed at runtime if the desired
+ backend has his option `VTK_SMP_ENABLE_<backend_name>` set to `ON`.
+ * `VTK_ENABLE_CATALYST` (default `OFF`): Enable the CatlystConduit module
+ and build the VTK Catalyst implementation. Depends on an external Catalyst.
+
+OpenGL-related options:
+
+Note that if OpenGL is used, there must be a "sensible" setup. Sanity checks
+exist to make sure a broken build is not being made. Essentially:
+
+- at least one rendering environment (X, Cocoa, SDL2, OSMesa, EGL, etc.) must
+ be available;
+- OSMesa and EGL conflict with each other; and
+- OSMesa only supports off-screen rendering and is therefore incompatible with
+ Cocoa, X, and SDL2.
+
+ * `VTK_USE_COCOA` (default `ON`; requires macOS): Use Cocoa for
+ render windows.
+ * `VTK_USE_X` (default `ON` for Unix-like platforms except macOS,
+ iOS, and Emscripten, `OFF` otherwise): Use X for render windows.
+ * `VTK_USE_SDL2` (default `ON` for Emscripten, `OFF` otherwise): Use
+ SDL2 for render windows.
+ * `VTK_OPENGL_HAS_OSMESA` (default `OFF`): Use to indicate that the
+ OpenGL library being used supports offscreen Mesa rendering
+ (OSMesa).
+ * `VTK_OPENGL_USE_GLES` (default `OFF`; forced `ON` for Android):
+ Whether to use OpenGL ES API for OpenGL or not.
+ * `VTK_OPENGL_HAS_EGL` (default `ON` for Android, `OFF` otherwise):
+ Use to indicate that the OpenGL library being used supports EGL
+ context management.
+ * `VTK_DEFAULT_EGL_DEVICE_INDEX` (default `0`; requires
+ `VTK_OPENGL_HAS_EGL`): The default EGL device to use for EGL render
+ windows.
+ * `VTK_DEFAULT_RENDER_WINDOW_OFFSCREEN` (default `OFF`): Whether to default
+ to offscreen render windows by default or not.
+ * `VTK_USE_OPENGL_DELAYED_LOAD` (default `OFF`; requires Windows and CMake >=
+ 3.13): If set, use delayed loading to load the OpenGL DLL at runtime.
+ * `VTK_DEFAULT_RENDER_WINDOW_HEADLESS` (default `OFF`; only available if
+ applicable): Default to a headless render window.
+ * `VTK_USE_WIN32_OPENGL` (default `ON` for Windows, forced `OFF` otherwise):
+ Use Win32 APIs for render windows (typically only relevant for OSMesa on
+ Windows builds).
+
+More advanced options:
+
+ * `VTK_ABI_NAMESPACE_NAME` (default `<DEFAULT>` aka `""`): If set, VTK will
+ wrap all VTK public symbols in an
+ `inline namespace <VTK_ABI_NAMESPACE_NAME>` to allow runtime co-habitation
+ with different VTK versions.
+ * `VTK_BUILD_DOCUMENTATION` (default `OFF`): If set, VTK will build its API
+ documentation using Doxygen.
+ * `VTK_BUILD_SPHINX_DOCUMENTATION` (default `OFF`): If set, VTK will build its sphinx
+ documentation website.
+ * `VTK_BUILD_ALL_MODULES` (default `OFF`): If set, VTK will enable all
+ modules not disabled by other features.
+ * `VTK_ENABLE_REMOTE_MODULES` (default `ON`): If set, VTK will try to build
+ remote modules (the `Remote` directory). If unset, no remote modules will
+ build.
+ * `VTK_ENABLE_EXTRA_BUILD_WARNINGS` (default `OFF`; requires CMake >= 3.19):
+ If set, VTK will enable additional build warnings.
+ * `VTK_ENABLE_EXTRA_BUILD_WARNINGS_EVERYTHING` (default `OFF`; requires
+ `VTK_ENABLE_EXTRA_BUILD_WARNINGS` and `-Weverything` support): If set, VTK
+ will enable all build warnings (with some explicitly turned off).
+ * `VTK_USE_EXTERNAL` (default `OFF`): Whether to prefer external third
+ party libraries or the versions VTK's source contains.
+ * `VTK_TARGET_SPECIFIC_COMPONENTS` (default `OFF`): Whether to install
+ files into target-specific components (`<TARGET>-runtime`,
+ `<TARGET>-development`, etc.) or general components (`runtime`,
+ `development`, etc.)
+ * `VTK_VERSIONED_INSTALL` (default `ON`): Whether to add version numbers to
+ VTK's include directories and library names in the install tree.
+ * `VTK_CUSTOM_LIBRARY_SUFFIX` (default depends on `VTK_VERSIONED_INSTALL`):
+ The custom suffix for libraries built by VTK. Defaults to either an empty
+ string or `X.Y` where `X` and `Y` are VTK's major and minor version
+ components, respectively.
+ * `VTK_INSTALL_SDK` (default `ON`): If set, VTK will install its headers,
+ CMake API, etc. into its install tree for use.
+ * `VTK_FORBID_DOWNLOADS` (default `OFF`): If set, VTK will error on any
+ network activity required during the build (namely remote modules and
+ testing data).
+ * `VTK_DATA_STORE` (default is complicated): If set or detected, points to
+ where VTK external data will be stored or looked up.
+ * `VTK_DATA_EXCLUDE_FROM_ALL` (default is complicated, but
+ generally `OFF`): If set or detected, data downloads will only
+ happen upon explicit request rather than through the build's
+ default target.
+ * `VTK_RELOCATABLE_INSTALL` (default `ON`): If set, the install tree will be
+ relocatable to another path. If unset, the install tree may be tied to the
+ build machine with absolute paths, but finding dependencies in
+ non-standard locations may require work without passing extra information
+ when consuming VTK.
+ * `VTK_UNIFIED_INSTALL_TREE` (default `OFF`): If set, the install tree is
+ stipulated to be a unified install tree of VTK and all of its dependencies;
+ a unified tree usually simplifies things including, but not limited to,
+ the Python module paths, library search paths, and plugin searching. This
+ option is irrelevant if a relocatable install is requested as such setups
+ assume that dependencies are set up either via a unified tree or some other
+ mechanism such as modules).
+ * `VTK_ENABLE_SANITIZER` (default `OFF`): Whether to enable sanitization of
+ the VTK codebase or not.
+ * `VTK_SANITIZER` (default `address`; requires `VTK_ENABLE_SANITIZER`): The
+ sanitizer to use.
+ * `VTK_USE_LARGE_DATA` (default `OFF`; requires `VTK_BUILD_TESTING`):
+ Whether to enable tests which use "large" data or not (usually used to
+ reduce the amount of data downloading required for the test suite).
+ * `VTK_USE_HIP` (default `OFF`; requires CMAKE >= 3.21 and NOT `VTK_USE_CUDA`)
+ Whether [HIP][hip] support will be available or not.
+ * `VTK_LEGACY_REMOVE` (default `OFF`): If set, VTK will disable legacy,
+ deprecated APIs.
+ * `VTK_LEGACY_SILENT` (default `OFF`; requires `VTK_LEGACY_REMOVE` to be
+ `OFF`): If set, usage of legacy, deprecated APIs will not cause warnings.
+ * `VTK_USE_FUTURE_CONST` (default `OFF`): If set, the `VTK_FUTURE_CONST`
+ macro expands to `const`; otherwise it expands to nothing. This is used to
+ incrementally add more const correctness to the codebase while making it
+ opt-in for backwards compatibility.
+ * `VTK_USE_FUTURE_BOOL` (default `OFF`): If set, the `vtkTypeBool`
+ typedef is defined to `bool`; otherwise it's `int`. VTK was created before
+ C++ even had `bool`, and so its oldest code used `int`. Set to `ON` to opt in
+ to using more real `bool`s, set to `OFF` only if required for backwards
+ compatibility.
+ * `VTK_USE_TK` (default `OFF`; requires `VTK_WRAP_PYTHON`): If set, VTK will
+ enable Tkinter support for VTK widgets.
+ * `VTK_BUILD_COMPILE_TOOLS_ONLY` (default `OFF`): If set, VTK will compile
+ just its compile tools for use in a cross-compile build.
+ * `VTK_SERIAL_TESTS_USE_MPIEXEC` (default `OFF`): Used on HPC to run
+ serial tests on compute nodes. If set, it prefixes serial tests with
+ "${MPIEXEC_EXECUTABLE}" "${MPIEXEC_NUMPROC_FLAG}" "1" ${MPIEXEC_PREFLAGS}
+ * `VTK_WINDOWS_PYTHON_DEBUGGABLE` (default `OFF`): Set to `ON` if using a
+ debug build of Python.
+ * `VTK_WINDOWS_PYTHON_DEBUGGABLE_REPLACE_SUFFIX` (default `OFF`): Set to `ON`
+ to use just a `_d` suffix for Python modules.
+ * `VTK_BUILD_PYI_FILES` (default `OFF`): Set to `ON` to build `.pyi` type
+ hint files for VTK's Python interfaces.
+ * `VTK_DLL_PATHS` (default `""` or `VTK_DLL_PATHS` from the environment): If
+ set, these paths will be added via Python 3.8's `os.add_dll_directory`
+ mechanism in order to find dependent DLLs when loading VTK's Python
+ modules. Note that when using the variable, paths are in CMake form (using
+ `/`) and in the environment are a path list in the platform's preferred
+ format.
+ * `VTK_ENABLE_VR_COLLABORATION` (default `OFF`): If `ON`, includes support
+ for multi client VR collaboration. Requires libzmq and cppzmq external libraries.
+ * `VTK_SMP_ENABLE_<backend_name>` (default `OFF` if needs an external library otherwise `ON`):
+ If set, builds with the specified SMPTools backend implementation that can be
+ changed on runtime with `VTK_SMP_BACKEND_IN_USE` environment variable.
+ * `VTK_USE_VIDEO_FOR_WINDOWS` (default `OFF`; requires Windows): Enable the
+ `vtkAVIWriter` class in the `VTK::IOMovie` module.
+ * `VTK_USE_VIDEO_FOR_WINDOWS_CAPTURE` (default `OFF`; requires Windows):
+ Enable the `vtkWin32VideoSource` class in the `VTK::IOVideo` module.
+ * `VTK_USE_MICROSOFT_MEDIA_FOUNDATION` (default `OFF`; requires Windows):
+ Enable the `vtkMP4Writer` class in the `VTK::IOMovie` module.
+ * `VTK_USE_64BIT_TIMESTAMPS` (default `OFF`; forced on for 64-bit builds):
+ Build with 64-bit `vtkMTimeType`.
+ * `VTK_USE_64BIT_IDS` (default `OFF` for 32-bit builds; `ON` for 64-bit
+ builds): Whether `vtkIdType` should be 32-bit or 64-bit.
+ * `VTK_DEBUG_LEAKS` (default `OFF`): Whether VTK will report leaked
+ `vtkObject` instances at process destruction or not.
+ * `VTK_DEBUG_RANGE_ITERATORS` (default `OFF`; requires a `Debug` build):
+ Detect errors with `for-range` iterators in VTK (note that this is very
+ slow).
+ * `VTK_ALWAYS_OPTIMIZE_ARRAY_ITERATORS` (default `OFF`; requires `NOT
+ VTK_DEBUG_RANGE_ITERATORS`): Optimize `for-range` array iterators even in
+ `Debug` builds.
+ * `VTK_ALL_NEW_OBJECT_FACTORY` (default `OFF`): If `ON`, classes using
+ `vtkStandardNewMacro` will use `vtkObjectFactoryNewMacro` allowing
+ overrides to be available even when not explicitly requested through
+ `vtkObjectFactoryNewMacro` or `vtkAbstractObjectFactoryNewMacro`.
+ * `VTK_ENABLE_VTKM_OVERRIDES` (default `OFF`): If `ON`, enables factory override
+ of certain VTK filters by their VTK-m counterparts. There is also a runtime
+ switch that can be used to enable/disable the overrides at run-time (on by default).
+ It can be accessed using the static function `vtkmFilterOverrides::SetEnabled(bool)`.
+ * `VTK_GENERATE_SPDX` (default `OFF`): If `ON`, SPDX file will be generated at build time
+ and installed for each module and third party, in order to be able to create a SBOM.
+ See [](/api/cmake/ModuleSystem.md#spdx-files-generation) and
+ [](/advanced/spdx_and_sbom.md) for more info.
+
+`vtkArrayDispatch` related options:
+
+The `VTK_DISPATCH_<array_type>_ARRAYS` options (default `OFF` for all but AOS) enable the
+specified type of array to be included in a dispatch type list. Explicit arrays (such as
+AOS, SOA and Typed) are included in the `vtkArrayDispatchTypeList.h` while
+`vtkArrayDispatchImplicitTypeList.h` includes both explicit and implicit arrays. The implicit
+array framework is included in the `CommonImplicitArrays` module. The following array types
+currently exist for use with the VTK dispatch mechanism:
+
+ * `VTK_DISPATCH_AOS_ARRAYS` (default `ON`): includes dispatching for the commonly used
+ "array-of-structure" ordered arrays derived from `vtkAOSDataArrayTemplate`
+ * `VTK_DISPATCH_SOA_ARRAYS` (default `OFF`): includes dispatching for "structure-of-array"
+ ordered arrays derived from `vtkSOADataArrayTemplate`
+ * `VTK_DISPATCH_TYPED_ARRAYS` (default `OFF`): includes dispatching for arrays derived
+ from `vtkTypedDataArray`
+ * `VTK_DISPATCH_AFFINE_ARRAYS` (default `OFF`): includes dispatching for linearly varying
+ `vtkAffineArray`s as part of the implicit array framework
+ * `VTK_DISPATCH_CONSTANT_ARRAYS` (default `OFF`): includes dispatching for constant arrays
+ `vtkConstantArray` as part of the implicit array framework
+ * `VTK_DISPATCH_STD_FUNCTION_ARRAYS` (default `OFF`): includes dispatching for arrays with
+ an `std::function` backend `vtkStdFunctionArray` as part of the implicit array framework
+ * `VTK_DISPATCH_COMPOSITE_ARRAYS` (default `OFF`): includes dispatching of arrays with a
+ `vtkCompositeImplicitBackend` backend, `vtkCompositeArray`, as part of the implicit array
+ framework
+ * `VTK_DISPATCH_INDEXED_ARRAYS` (default `OFF`): includes dispatching of arrays with a
+ `vtkIndexedImplicitBackend` backend, `vtkIndexedArray`, as part of the implicit array
+ framework
+
+The outlier in terms of dispatch support is the family of arrays derived from
+`vtkScaledSOADataArrayTemplate` which are automatically included in dispatch when built setting
+the `VTK_BUILD_SCALED_SOA_ARRAYS`.
+
+```{warning}
+Adding increasing numbers of arrays in the dispatch mechanism can greatly slow down compile times.
```
+
+The VTK module system provides a number of variables to control modules which
+are not otherwise controlled by the other options provided.
+
+ * `VTK_MODULE_USE_EXTERNAL_<name>` (default depends on `VTK_USE_EXTERNAL`):
+ Use an external source for the named third-party module rather than the
+ copy contained within the VTK source tree.
+
+ ````{warning}
+ Activating this option within an interactive cmake configuration (i.e. ccmake, cmake-gui)
+ could end up finding libraries in the standard locations rather than copies
+ in non-standard locations.
+
+ It is recommended to pass the variables necessary to find the intended external package to
+ the first configure to avoid finding unintended copies of the external package.
+ The variables which matter depend on the package being found, but those ending with
+ `_LIBRARY` and `_INCLUDE_DIR` as well as the general CMake `find_package` variables ending
+ with `_DIR` and `_ROOT` are likely candidates.
+
+ Example:
+ ```
+ ccmake -D HDF5_ROOT:PATH=/home/user/myhdf5 ../vtk/sources
+ ```
+ ````
+
+ * `VTK_MODULE_ENABLE_<name>` (default `DEFAULT`): Change the build settings
+ for the named module. Valid values are those for the module system's build
+ settings (see below).
+ * `VTK_GROUP_ENABLE_<name>` (default `DEFAULT`): Change the default build
+ settings for modules belonging to the named group. Valid values are those
+ for the module system's build settings (see below).
+
+For variables which use the module system's build settings, the valid values are as follows:
+
+ * `YES`: Require the module to be built.
+ * `WANT`: Build the module if possible.
+ * `DEFAULT`: Use the settings by the module's groups and
+ `VTK_BUILD_ALL_MODULES`.
+ * `DONT_WANT`: Don't build the module unless required as a dependency.
+ * `NO`: Do not build the module.
+
+If any `YES` module requires a `NO` module, an error is raised.
+
+[cuda]: https://developer.nvidia.com/cuda-zone
+[hip]: https://en.wikipedia.org/wiki/ROCm
+[mpi]: https://www.mcs.anl.gov/research/projects/mpi
diff --git a/Documentation/docs/design_documents/IOLegacyInformationFormat.md b/Documentation/docs/design_documents/IOLegacyInformationFormat.md
index ce3589157f19beddaa8cd31ccdeced3f0d7993e0..fcafbf6b8374b6e9a4a9f3c7c4b01e5936742f31 100644
--- a/Documentation/docs/design_documents/IOLegacyInformationFormat.md
+++ b/Documentation/docs/design_documents/IOLegacyInformationFormat.md
@@ -1,2 +1,164 @@
-```{include} ../../Doxygen/IOLegacyInformationFormat.md
+# VTK Legacy Reader/Writer Information Format
+
+## Overview
+
+The legacy vtk data file readers / writers store certain `vtkInformation`
+entries that are set on `vtkAbstractArray`'s `GetInformation()` object. Support
+is currently limited to numeric and string information keys, both single- and
+vector-valued. Only the information objects attached to arrays are encoded.
+
+## Array Metadata Blocks
+
+A block of metadata may immediately follow the specification of an array.
+Whitespace is permitted between the array data and the opening `METADATA` tag.
+The metadata block is terminated by an empty line.
+
+```
+# vtk DataFile Version 4.1
+vtk output
+ASCII
+DATASET UNSTRUCTURED_GRID
+POINTS 6 float
+0 0 0 1 0 0 0.5 1 0
+0.5 0.5 1 0.5 -1 0 0.5 -0.5 1
+
+METADATA
+COMPONENT_NAMES
+X%20coordinates
+Y%20coordinates
+Z%20coordinates
+INFORMATION 8
+NAME Double LOCATION TestKey
+DATA 1
+NAME DoubleVector LOCATION TestKey
+DATA 3 1 90 260
+NAME IdType LOCATION TestKey
+DATA 5
+NAME String LOCATION TestKey
+DATA Test%20String!%0ALine2
+NAME Integer LOCATION TestKey
+DATA 408
+NAME IntegerVector LOCATION TestKey
+DATA 3 1 5 45
+NAME StringVector LOCATION TestKey
+DATA 3
+First
+Second%20(with%20whitespace!)
+Third%20(with%0Anewline!)
+NAME UnsignedLong LOCATION TestKey
+DATA 9
+
+CELLS 3 15
+4 0 1 2 3
+4 0 4 1 5
+4 5 3 1 0
+
+CELL_TYPES 3
+10
+10
+10
+
+CELL_DATA 3
+FIELD FieldData 1
+vtkGhostType 1 3 unsigned_char
+0 1 1
+METADATA
+COMPONENT_NAMES
+Ghost%20level%20information
+INFORMATION 1
+NAME UNITS_LABEL LOCATION vtkDataArray
+DATA radians
+
+```
+
+As shown, a metadata block can have two sections, `COMPONENT_NAMES` and
+`INFORMATION`. The `INFORMATION` tag is followed by the number of information
+keys that follow.
+
+### COMPONENT_NAMES
+
+If the `METADATA` block contains the line `COMPONENT_NAMES`, the following lines
+are expected to be encoded strings containing the names of each component. There
+must be one line per component.
+
+### INFORMATION
+
+If the `METADATA` block contains the line `INFORMATION`, the number of information
+keys is read from the INFORMATION line and `vtkInformation` data that follows is
+parsed. The general form of a single valued information entry is:
+
+```
+NAME [key name] LOCATION [key location (e.g. class name)]
+DATA [value]
+```
+
+A vector information key is generally represented as:
+
+```
+NAME [key name] LOCATION [key location (e.g. class name)]
+DATA [vector length] [value0] [value1] [value2] ...
+```
+
+The exception is a string vector, which contains encoded entries separated by
+newlines.
+
+Specific examples of supported key types:
+
+#### vtkInformationDoubleKey
+
+```
+NAME Double LOCATION TestKey
+DATA 1
+```
+
+#### vtkInformationDoubleVectorKey
+
+```
+NAME DoubleVector LOCATION TestKey
+DATA 3 1 90 260
+```
+
+#### vtkInformationIdTypeKey
+
+```
+NAME IdType LOCATION TestKey
+DATA 5
+```
+
+#### vtkInformationStringKey
+
+```
+NAME String LOCATION TestKey
+DATA Test%20String!%0ALine2
+```
+
+#### vtkInformationIntegerKey
+
+```
+NAME Integer LOCATION TestKey
+DATA 408
+```
+
+#### vtkInformationIntegerVectorKey
+
+```
+NAME IntegerVector LOCATION TestKey
+DATA 3 1 5 45
+```
+
+#### vtkInformationStringVectorKey
+
+```
+NAME StringVector LOCATION TestKey
+DATA 3
+First
+Second%20(with%20whitespace!)
+Third%20(with%0Anewline!)
+```
+
+#### vtkInformationUnsignedLongKey
+
+```
+NAME UnsignedLong LOCATION TestKey
+DATA 9
```
diff --git a/Documentation/docs/design_documents/IOXMLInformationFormat.md b/Documentation/docs/design_documents/IOXMLInformationFormat.md
index 8a1c8de07d88981e1691d254e6f45d44fb4b14f2..7bf63ef2996ad4c824b1d49e8e0f3abbec81cb3b 100644
--- a/Documentation/docs/design_documents/IOXMLInformationFormat.md
+++ b/Documentation/docs/design_documents/IOXMLInformationFormat.md
@@ -1,2 +1,121 @@
-```{include} ../../Doxygen/IOXMLInformationFormat.md
+# VTK XML Reader/Writer Information Format
+
+## Overview
+
+The vtk xml data file readers / writers store certain `vtkInformation`
+entries that are set on `vtkAbstractArray`'s `GetInformation()` object. Support
+is currently limited to numeric and string information keys, both single- and
+vector-valued. Only the information objects attached to arrays are written/read.
+
+## Array Information
+
+Array information is embedded in the `<DataArray>` XML element as a series of
+`<InformationKey>` elements. The required attributes `name` and `location`
+specify the name and location strings associated with the key -- for instance,
+the `vtkDataArray::UNITS_LABEL()` key has `name="UNITS_LABEL"` and
+`location="vtkDataArray"`. The `length` attribute is required for vector keys.
+
+```{code-block} xml
+:force: true
+<DataArray [...]>
+ <InformationKey name="KeyName" location="KeyLocation" [ length="N" ]>
+ [...]
+ </InformationKey>
+ <InformationKey [...]>
+ [...]
+ </InformationKey>
+ [...]
+</DataArray>
+```
+
+Specific examples of supported key types:
+
+### vtkInformationDoubleKey
+
+```xml
+<InformationKey name="Double" location="XMLTestKey">
+ 1
+</InformationKey>
+```
+
+### vtkInformationDoubleVectorKey
+
+```xml
+<InformationKey name="DoubleVector" location="XMLTestKey" length="3">
+ <Value index="0">
+ 1
+ </Value>
+ <Value index="1">
+ 90
+ </Value>
+ <Value index="2">
+ 260
+ </Value>
+</InformationKey>
+```
+
+### vtkInformationIdTypeKey
+
+```xml
+<InformationKey name="IdType" location="XMLTestKey">
+ 5
+</InformationKey>
+```
+
+### vtkInformationStringKey
+
+```xml
+<InformationKey name="String" location="XMLTestKey">
+ Test String!
+Line2
+</InformationKey>
+```
+
+### vtkInformationIntegerKey
+
+```xml
+<InformationKey name="Integer" location="XMLTestKey">
+ 408
+</InformationKey>
+```
+
+### vtkInformationIntegerVectorKey
+
+```xml
+<InformationKey name="IntegerVector" location="XMLTestKey" length="3">
+ <Value index="0">
+ 1
+ </Value>
+ <Value index="1">
+ 5
+ </Value>
+ <Value index="2">
+ 45
+ </Value>
+</InformationKey>
+```
+
+### vtkInformationStringVectorKey
+
+```xml
+<InformationKey name="StringVector" location="XMLTestKey" length="3">
+ <Value index="0">
+ First
+ </Value>
+ <Value index="1">
+ Second (with whitespace!)
+ </Value>
+ <Value index="2">
+ Third (with
+newline!)
+ </Value>
+</InformationKey>
+```
+
+### vtkInformationUnsignedLongKey
+
+```xml
+<InformationKey name="UnsignedLong" location="XMLTestKey">
+ 9
+</InformationKey>
```
diff --git a/Documentation/docs/design_documents/IOXMLTimeInFieldData.md b/Documentation/docs/design_documents/IOXMLTimeInFieldData.md
index 396d29ea3821e072ab324566c31243026ee538a1..0d1f00512764abed190b740751b846e5a562e23c 100644
--- a/Documentation/docs/design_documents/IOXMLTimeInFieldData.md
+++ b/Documentation/docs/design_documents/IOXMLTimeInFieldData.md
@@ -1,2 +1,32 @@
-```{include} ../../Doxygen/IOXMLTimeInFieldData.md
+# Field Data as Time Meta-Data in VTK XML File Formats
+
+As of VTK 8.2, VTK XML readers and writers support embedding time
+meta-data as a field array. This is demonstrated best with an example:
+
+```xml
+<VTKFile type="PolyData" version="1.0" byte_order="LittleEndian" header_type="UInt64">
+ <PolyData>
+ <FieldData>
+ <DataArray type="Float64" Name="TimeValue" NumberOfTuples="1">1.24
+ </DataArray>
+ </FieldData>
+ ...
+</VTKFile>
```
+
+Here TimeValue is a regular double precision array that has a single value of 1.24.
+The XML readers will treat this array in a special way. When they encounter this array
+during the meta-data stage (`RequestInformation()`), they will read the value from
+this array and generate a `vtkStreamingDemandDrivenPipeline::TIME_STEPS()` key
+in the output information containing this value.
+
+In addition, the XML writers will generate a field array of name TimeValue in the
+output, if they encounter time value in their input (`vtkDataObject::DATA_TIME_STEP()`).
+This is done even if the data does not have a TimeValue array. Furthermore, even such
+an array exists, it will be replaced with one that contains the value from
+`vtkDataObject::DATA_TIME_STEP()` to make sure that the value is consistent with the
+pipeline value.
+
+This change may appear pointless on its own as a single time value is not very useful.
+Its main use is when reading file series as it is done by ParaView's file (time) series
+readers.
diff --git a/Documentation/docs/design_documents/VTKFileFormats.md b/Documentation/docs/design_documents/VTKFileFormats.md
index e103fc0cb674d9113b7e02239d725f61c22a199e..015e862e85e7c94651f79a3681626c4e00ded425 100644
--- a/Documentation/docs/design_documents/VTKFileFormats.md
+++ b/Documentation/docs/design_documents/VTKFileFormats.md
@@ -1083,9 +1083,9 @@ using the following formulas:
```{figure} poly_data_hdf_schema.png
----
-width=640
----
+:width: 640px
+:align: center
+
Figure 8. - Poly Data VTKHDF File Format
```
@@ -1159,9 +1159,9 @@ absence of a data set, the appropriate geometry offsetting for the time step is
place.
```{figure} transient_hdf_schema.png
----
-width=640
----
+:width: 640px
+:align: center
+
Figure 10. - Transient Data VTKHDF File Format
```
diff --git a/Documentation/docs/design_documents/data_assemply.md b/Documentation/docs/design_documents/data_assemply.md
index bb65fc87a9dc62d6773ed1fa6bbc2bf3601fc967..9cd2d733ad2aa97874108c81c780f721af721220 100644
--- a/Documentation/docs/design_documents/data_assemply.md
+++ b/Documentation/docs/design_documents/data_assemply.md
@@ -1,2 +1,108 @@
-```{include} ../../Doxygen/DataAssembly.md
-```
+# Data Assembly
+
+VTK 10.0 introduces a new mechanism for representing data hierarchies
+using vtkPartitionedDataSetCollection and vtkDataAssembly. This document
+describes the design details.
+
+## Data Model
+
+The design is based on three classes:
+
+* `vtkPartitionedDataSet` is a collection of datasets (not to be confused with
+ `vtkDataSet`).
+* `vtkPartitionedDataSetCollection` is a collection of `vtkPartitionedDataSet`s.
+* `vtkDataAssembly` defines the hierarchical relationships between items in a
+ `vtkPartitionedDataSetCollection`.
+
+### Partitioned Dataset
+
+`vtkPartitionedDataSet` is simply a collection of datasets that are to be
+treated as a logical whole. In data-parallel applications, each dataset may
+represent a partition of the complete dataset on the current worker process,
+rank, or thread. Each dataset in a `vtkPartitionedDataSet` is called a
+**partition**, implying it is only a part of a whole.
+
+All non-null partitions have similar field and attribute arrays. For example, if
+a `vtkPartitionedDataSet` comprises of `vtkDataSet` subclasses, all will have
+exactly the same number of point data/cell data arrays, with same names, same
+number of components, and same data types.
+
+### Partitioned Dataset Collection
+
+`vtkPartitionedDataSetCollection` is a collection of `vtkPartitionedDataSet`.
+Thus, it is simply a mechanism to group multiple `vtkPartitionedDataSet`
+instances together. Since each `vtkPartitionedDataSet` represents a whole dataset
+(not be confused with `vtkDataSet`), we can refer to each item in a
+`vtkPartitionedDataSetCollection` as a **partitioned-dataset**.
+
+Unlike items in the `vtkPartitionedDataSet`, there are no restrictions of consistency
+between each items, partitioned-datasets, in the `vtkPartitionedDataSetCollection`.
+Thus, in the multiblock-dataset parlance, each item in this collection can be thought
+of as a block.
+
+### Data Assembly
+
+`vtkDataAssembly` is a means to define an hierarchical organization of items in a
+`vtkPartitionedDataSetCollection`. This is literally a tree made up of named nodes.
+Each node in the tree can have associated dataset-indices. For a `vtkDataAssembly` is
+associated with a `vtkPartitionedDataSetCollection`, each of the
+dataset-indices is simply the index of a partitioned-dataset in the
+`vtkPartitionedDataSetCollection`. A dataset-index can be associated with multiple nodes in
+the assembly, however, a dataset-index cannot be associated with the same node more than once.
+
+An assembly provides an ability to define a more complex view of the raw data blocks in
+a more application-specific form. This is not much different than what could be achieved using simply
+a `vtkMultiBlockDataSet`. However, there are several advantages to this separation of storage
+(`vtkPartitionedDataSetCollection`) and organization (`vtkDataAssembly`). These will become clear as
+we cover different use-cases.
+
+While nodes in the data-assembly have unique ids, public facing algorithm APIs should not use them. For example
+an extract-block filter that allows users to choose which blocks (rather partitioned-datasets)
+to extract from vtkPartitionedDataSetCollection can expose an API that lets users provide
+path-expression to identify nodes in the associated data-assembly using their names.
+
+Besides accessing nodes by querying using their names, `vtkDataAssembly` also
+supports a mechanism to iterate over all nodes in depth-first or breadth-first
+order using a *visitor*. vtkDataAssemblyVisitor defines a API that can be
+implemented to do custom action as each node in the tree is visited.
+
+## Design Implications
+
+1. Since `vtkPartitionedDataSet` is simply parts of a whole, there is no specific significance
+ to the number of partitions. In distributed pipelines, for example, a `vtkPartitionedDataSet`
+ on each rank can have arbitrarily many partitions. Furthermore, filters can add/remove
+ partitions as needed. Since the `vtkDataAssembly` never refers to individual partitions, this has no
+ implication to filters that use the hierarchical relationships.
+
+2. When constructing `vtkPartitionedDataSetCollection` in distributed data-parallel cases,
+ each rank should have exactly the same number of partitioned-datasets.
+ In this case, each `vtkPartitionedDataSet` at a specific index across all ranks together is
+ treated as a whole dataset. Similarly, the `vtkDataAssembly` on each should be identical.
+
+3. When developing filters, it is worth considering whether the filter really is a
+ `vtkPartitionedDataSetCollection` filter or simply a `vtkPartitionedDataSet`-aware
+ filter that needs to operate on each `vtkPartitionedDataSet` individually. For example,
+ typical multiblock-aware filters like ghost-cell-generation, data-redistribution, etc.,
+ are simply `vtkPartitionedDataSet` filters. For `vtkPartitionedDataSet`-only filters,
+ when the input is a `vtkPartitionedDataSetCollection`, the executive takes care of looping
+ over each of the partitioned-dataset in the collection, thus simplifying the filter development.
+
+4. Filters that don't change the number of partitioned-datasets in a
+ vtkPartitionedDataSetCollection don't generally affect the relationships
+ between the partitioned-datasets and hence can largely pass through the
+ vtkDataAssembly. Only filter like extract-block that remove
+ partitioned-datasets need to update the vtkDataAssembly. There too,
+ vtkDataAssembly provides several convenience methods to update the tree with
+ ease.
+
+5. It is possible to develop a mapper that uses the `vtkDataAssembly`. Using
+ APIs that let users use path-queries to specify rendering properties for
+ various nodes, the mapper can support use-cases where the input structure
+ keeps changing but the relationships remain largely intact.
+ Since the same dataset-index can be associated with multiple nodes in a
+ `vtkDataAssembly`, the mapper can effectively support scene-graph like
+ capabilities where user can specify transforms, and other rendering
+ parameters, while reusing the heavy datasets. The mapper can easily tell if
+ a dataset has already been uploaded to the rendering pipeline since it will
+ have the same id and indeed be the same instance even if is being visited
+ through different branches in the tree.
diff --git a/Documentation/docs/design_documents/smptools.md b/Documentation/docs/design_documents/smptools.md
index 8fcdc23271e623423b4802386f022cd42b3505bb..1a25801d21e6c30c392e2b387cf6fb4286fe63a6 100644
--- a/Documentation/docs/design_documents/smptools.md
+++ b/Documentation/docs/design_documents/smptools.md
@@ -1,2 +1,320 @@
-```{include} ../../Doxygen/SMPTools.md
+# Parallel Processing with VTK's SMP Framework
+August 2022
+
+## Contributors
+Berk Geveci wrote the initial version of this document in 2013. The design and implementation of vtkSMPTools was strongly influenced by the [KAAPI thread scheduling system](https://www.researchgate.net/publication/221564735_KAAPI_A_thread_scheduling_runtime_system_for_data_flow_computations_on_cluster_of_multi-processors) and an associated Inria research report: [*VtkSMP: Task-based Parallel Operators for Accelerating VTK Filters*](https://hal.inria.fr/hal-00789814). Later contributors to this document include:
+- Timothee Couble
+- Charles Gueunet
+- Will Schroeder
+- Spiros Tsalikis
+
+Also note that several blog posts have been written about vtkSMPTools:
+- [Simple, Parallel Computing with vtkSMPTools](https://www.kitware.com/simple-parallel-computing-with-vtksmptools/)
+- [VTK Shared Memory Parallelism Tools, 2021 updates](https://www.kitware.com/vtk-shared-memory-parallelism-tools-2021-updates/)
+- [Ongoing VTK / ParaView Performance Improvements](https://www.kitware.com/ongoing-vtk-paraview-performance-improvements/)
+- [VTK/ParaView Filters: Performance Improvements](https://www.kitware.com/vtk-paraview-filters-performance-improvements/)
+
+## Introduction
+The overarching objective of vtkSMPTools, the SMP (symmetric multiprocessing) framework, is to provide an infrastructure to simplify the development of shared memory parallel algorithms in VTK. In addition, vtkSMPTools defines a simple, abstract API that drives several threading backends such as std::thread, TBB (i.e., Intel's Threading Building Blocks template library); and OpenMP; as well as supporting a sequential backend for testing and debugging. To achieve these objectives, we have developed three simple constructs to support basic SMP functionality:
+
+- Parallel building blocks / functions
+- Thread local storage
+- Atomic integers and associated operations. (Note, since C++11 this has been superseded by `std::atomic<>`. Also, `std::mutex` and `vtkAtomicMutex` are options.)
+
+vtkSMPTools is extremely easy to use, ensuring that the major challenge of creating parallel algorithms is not one of implementation, but rather the design of good, threaded algorithms. In the next sections we describe the basic concepts used in vtkSMPTools, and then demonstrate these concepts through example code. Of course, there are hundreds of vtkSMPTools implementations found in VTK which provide an excellent source of more complex examples. In the final section of this document we provide tips on how to design and implement vtkSMPTools-based algorithms.
+
+## Concepts
+
+The following are several high-level concepts that will help you understand and use vtkSMPTools.
+
+### The Age of Abundant Computing Cores
+Many early computational algorithms were designed and implemented in an era of limited computing resources: typically a single CPU was available with rudimentary memory models. Such limitations typically led to a frugal approach to writing algorithms, in particular approaches that minimized CPU utilization. However modern computing architectures commonly have many cores with multiple execution threads per core, and memory models have expanded to include a hierarchy of data caches to retrieve frequently used data more quickly. Also, many developers are inclined to think in terms of *sequential* algorithmic operations, partly due to the way in which we were trained but also because managing multiple simultaneous processes can take a lot of work and programmers are often pressed for time. But with growing data sizes, increasing computational demands, and the abundance of computing threads; it's clear that parallel approaches are essential to creating responsive and impactful software tools. It's important that VTK developers conceive and implement performant parallel algorithms to ensure that the system remain vital into the future.
+
+There are a variety of approaches to parallel computing, but two approaches - distributed computing and shared memory computing - are particularly relevant to VTK. In distributed computing, computational tasks are carried out in separate memory space and exchange information through message passing communication. In shared memory computing, information is exchanged through variables in shared memory space. Typically a flavor of MPI is used by VTK for distributed computing, plus VTK provides a variety of software constructs to support distributed computing. vtkSMPTools is used to implement shared memory computing with symmetric multiprocessing (SMP) approaches; i.e., where multiple processors are connected to a single, shared memory space. Distributed computing is more complex and scales best for extremely large data, while shared memory computing is simpler and works cell on single computers (desktop, laptop, mobile). Note that it is possible to combine distributed and shared computing in a VTK application.
+
+Besides MPI (for distributed computing) and vtkSMPTools (shared memory parallelism, typically on CPUs), be aware that VTK leverages another parallel processing toolkit for computing accelerators (e.g., GPUs). [vtk-m](https://m.vtk.org/) is a toolkit of scientific visualization algorithms for emerging processor architectures, supporting fine-grained concurrency for data analysis and visualization algorithms. Depending on the application, vtk-m may be a preferred solution for extreme scale computing. It is possible to mix all three forms of parallel computing frameworks into a single VTK application.
+
+### Fine- and Coarse-Grained Parallelism
+When parallelizing an algorithm, it is important to first consider the "dimension" (i.e., the way in which data is accessed via threads) over which to parallelize it. For example, VTK's Imaging modules parallelize many algorithms by assigning subsets of the input image (VOIs) to a thread safe function which processes them in parallel. Another example is parallelizing over blocks of a composite dataset (such as an AMR dataset). We refer to these examples as coarse-grained parallelism. On the other hand, we can choose points or cells as a dimension over which to parallelize access to a VTK dataset. Many algorithms simply loop over cells or points and are relatively trivial to parallelize this way. Here we refer to this approach as fine-grained parallelism. Note that some algorithms fall into a gray area. For example, if we parallelize streamline generation over seeds, is it fine- or coarse-grained parallelism?
+
+### Backends
+The SMP framework provides a thin abstraction over a number of threading backends. Currently, we support four backends: Sequential (serial execution); C++ std::thread referred to as STDThread; TBB (based on Intel’s TBB); and OpenMP. Note that the Sequential backend is useful for debugging but is typically not used unless no other backend can be made to work on the target platform. As discussed in the following, it's possible to build VTK with multiple backends, and switch between them at run-time.
+
+Backends are configured via CMake during the build process. Setting the CMake variables `VTK_SMP_ENABLE_OPENMP`, `VTK_SMP_ENABLE_SEQUENTIAL`, `VTK_SMP_ENABLE_STDTHREAD`, and `VTK_SMP_ENABLE_TBB` enables the inclusion of the appropriate SMP backend(s), and `VTK_SMP_IMPLEMENTATION_TYPE` can be used to select one of Sequential, OpenMP, TBB, and STDThread (this selects the default backend when VTK runs). Once VTK is built, setting the environment variable `VTK_SMP_BACKEND_IN_USE` can be used to select from multiple backends. (Note: `vtkSMPTools::SetBackend()` can be used from within a C++ application to select the backend as well -- for example `vtkSMPTools::SetBackend("TBB")` will select TBB.)
+
+### Thread Safety in VTK
+Probably the most important thing in parallelizing shared-memory algorithms is to make sure that all operations that occur in a parallel region are performed in a thread-safe way (i.e., avoid race conditions). Note that there is much in the VTK core functionality that is not thread-safe. The VTK community has an ongoing effort of cleaning this up and marking APIs that are thread-safe to use. At this point, probably the best approach is to double check by looking at the implementation. Also, we highly recommend using analysis tools such as ThreadSanitizer or Valgrind (with the Helgrind tool) to look for race conditions in problematic code.
+
+When coding parallel algorithms, be especially wary of insidious execution side effects. Such side effects typically result in simultaneous execution of code. For example, invoking `Update()` on a filter shared by multiple threads is a bad idea since simultaneous updates to that filter is likely doomed to fail. Also, some methods like `vtkPolyData::GetCellNeighbors()` internally invoke the one-time operation `BuildLinks()` in order to generate topological information. Similarly, the `BuildLocator()` method found in point and cell locators may be called as a side effect of a geoemtric query such as `vtkDataSet::FindCell()`. In such cases, prior to threaded execution, affected classes should be "primed" by explicitly invoking methods that produce side effects (e.g., call `BuildLinks()` directly on the `vtkPolyData`; or manually call `BuildLocator()` prior to using methods that require a locator).
+
+### Results Invariance
+A significant challenge to writing good threaded algorithms is to insure that they produce the same output each time they execute. For example, a threaded sort operation may order *identical* set elements differently each time the sort is run depending on the order in which data is processed by different computing threads. (This is related to the C++ standard providing the `std::stable_sort` algorithm.) Even simple threaded operation such as summing a list of numbers can produce different results, since the order and partitioning of data during threading may result in round off effects. Since sequential algorithms implicitly order their operations, and threading typically does not do so (unless extensive use of locks, barriers, etc. are used), a sequential algorithm may produce different results than a threaded algorithm, and even across multiple runs threaded algorithms may produce results that vary across each run. Such behaviors are disturbing to users, and make testing difficult. In VTK, we aim to write algorithms that are results invariant.
+
+### Show Me the Code
+The vtkSMPTools class defined in `VTK\Common\Core\vtkSMPTools.h` provides detailed documentation and further implementation details. To find examples of vtkSMPTools in use, simply search for VTK C++ classes that include this header file.
+
+## Implementation Overview
+As mentioned previously, vtkSMPTools provides a few, simple programmatic building blocks; support for thread-local storage; and support for atomics. In this section we provide high-level descriptions of these building blocks. Then in the following section we provide implementation details.
+
+### Functional Building Blocks
+The core, functional building blocks of vtkSMPTools are as follows. See `vtkSMPTools.h` for details.
+* `For(begin, end, functor)` - a for loop over the range [begin,end) executing the functor each time.
+* `Fill(begin, end, value)` - assign the given value to the elements in range [begin,end) (a drop in replacement for `std::fill()`).
+* `Sort(begin,end)` and `Sort(begin,end,compare)` - sort the elements in range [begin,end) using the optional comparison function (a drop in replacement for `std::sort()`).
+* `Transform()` - a drop in replacement for `std::transform()`.
+
+Note that the ranges [begin,end) may be expressed via integral (`vtkIdType`) types for example point or cell ids, or C++ iterators.
+
+Of special interest is the `functor` invoked in the `For()` loop. The functor is a class/struct which requires defining the `void operator()(begin,end)` method. Given a range defined by `[begin, end)` and the functor, `For()` will call the functor’s `operator()`, usually in parallel, over a number of subranges of `[begin, end)`. The functor may also implement methods to initialize data associated with each thread (`void Initialize()`), and to composite the results of executing the `For()` loop into a final result (i.e., `void Reduce()`).
+
+With these few building blocks, powerful threaded algorithms can easily be written. In many cases, the `For()` loop is all that is needed.
+
+### Thread Local Storage
+Often times parallel algorithms produce intermediate results that are combined to produce a final result. For example, to sum a long list of numbers, each thread may sum just a subset of the numbers, and when completed the intermediate sums from each thread can be combined to produce a final summation. So the ability to maintain intermediate data associated with each thread is valuable. This is the purpose of thread local storage.
+
+Thread local storage is generally referred to memory that is accessed by one thread only. In the SMP framework, vtkSMPThreadLocal and vtkSMPThreadLocalObject enable the creation of objects local to executing threads. The main difference between the two is that vtkSMPThreadLocalObject makes it easy to manage vtkObject and subclasses by allocating and deleting them appropriately. Thread local storage almost always requires definition of the `Initialize()` and `Reduce()` methods to initialize local storage, and then combine it once the `For()` loop completes.
+
+One important performance trick with thread local storage, is that temporary variables may be defined and then used in the execution of `operator()`. For example, instantiating temporary objects such as vtkGenericCell, vtkIdList, and other C++ containers or classes can be relatively slow. Sometimes it's much faster to create and initialize them once (when the thread is created), and then "reset" them in each invocation of `operator()`.
+
+### Atomics
+Another very useful tool when developing shared memory parallel algorithms is atomic integers. Atomic integers provide the ability to manipulate integer values in a way that can’t be interrupted by other threads. A very common use case for atomic integers is implementing global counters. For example, in VTK, the modified time (MTime) global counter and vtkObject’s reference count are implemented as atomic integers.
+
+Prior to C++11, vtkSMPTools had an internal implementation for atomic integers. However, this implementation is now obsolete in favor of `std::atomic<>`. C++ also provides `std::mutex' and 'std::lock_guard<>`; and VTK provides a lightweight spinlock `vtkAtomicMutex` which may be faster than using mutexes.
+
+## Implementation Examples
+In the subsections below, we describe the SMP framework in more detail and provide examples of how it can be used.
+
+### Functors and Parallel For
+The `vtkSMPTools::For()` parallel for is the core computational construct of vtkSMPTools. It's use is as shown in the following example which evaluates points against a set of planes, and adjusts the planes to "bound" the points (see `vtkHull.cxx` and `VTK/Common/DataModel/Testing/Cxx/TestSMPFeatures.cxx`).
```
+ vtkNew<vtkPoints> pts;
+ pts->SetDataTypeToFloat();
+ pts->SetNumberOfPoints(numPts);
+ for ( auto i=0; i < numPts; ++i)
+ {
+ pts->SetPoint(i, vtkMath::Random(-1,1), vtkMath::Random(-1,1), vtkMath::Random(-1,1));
+ }
+```
+Now define the functor:
+```
+struct HullFunctor
+{
+ vtkPoints *InPts;
+ std::vector<double>& Planes;
+
+ HullFunctor(vtkPoints *inPts, std::vector<double>& planes) : InPts(inPts), Planes(planes) {}
+
+ void operator()(vtkIdType ptId, vtkIdType endPtId)
+ {
+ vtkPoints *inPts = this->InPts;
+ std::vector<double>& planes = this->Planes;
+ auto numPlanes = planes.size() / 4;
+
+ for (; ptId < endPtId; ++ptId)
+ {
+ double v, coord[3];
+ inPts->GetPoint(ptId, coord);
+ for (size_t j = 0; j < numPlanes; j++)
+ {
+ v = -(planes[j * 4 + 0] * coord[0] + planes[j * 4 + 1] * coord[1] +
+ planes[j * 4 + 2] * coord[2]);
+ // negative means further in + direction of plane
+ if (v < planes[j * 4 + 3])
+ {
+ planes[j * 4 + 3] = v;
+ }
+ }
+ }
+ }
+}; //HullFunctor
+```
+To use the functor and invoke `vtkSMPTools::For()`:
+```
+ HullFunctor hull(pts,planes);
+ vtkSMPTools::For(0,numPts, hull);
+```
+Note that same code can be conveniently and compactly defined inline via a C++ lambda function. Lambdas are particularly useful when thread local storage and/or local variable are not required.
+```
+ vtkSMPTools::For(0, numPts, [&](vtkIdType ptId, vtkIdType endPtId) {
+ for (; ptId < endPtId; ++ptId)
+ {
+ double v, coord[3];
+ pts->GetPoint(ptId, coord);
+ for (auto j = 0; j < numPlanes; j++)
+ {
+ v = -(planes[j * 4 + 0] * coord[0] + planes[j * 4 + 1] * coord[1] +
+ planes[j * 4 + 2] * coord[2]);
+ // negative means further in + direction of plane
+ if (v < planes[j * 4 + 3])
+ {
+ planes[j * 4 + 3] = v;
+ }
+ }
+ }
+ }); // end lambda
+```
+With alternative signatures for `For()` it is possible to provide a grain parameter. Grain is a hint to the underlying backend about the coarseness of the typical range when parallelizing a for loop. If you don’t know what grain will work best for a particular problem, omit the grain specification and let the backend find a suitable grain. TBB in particular does a good job with this. Sometimes, you can eek out a little bit more performance by setting the grain just right. Too small, the task queuing overhead will be too much. Too little, load balancing will suffer.
+
+### Thread Local Storage
+Thread local storage is generally referred to memory that is accessed by one thread only. In the SMP framework, vtkSMPThreadLocal and vtkSMPThreadLocalObject enable the creation objects local to executing threads. The main difference between the two is that vtkSMPThreadLocalObject makes it easy to manage vtkObject and subclasses by allocating and deleting them appropriately.
+
+Below is an example of thread local objects in use. This example computes the bounds of a set of points represented by a vtkFloatArray. Note in particular the introduction of the `Initialize()` and `Reduce()` methods:
+```
+using BoundsArray = std::array<double,6>;
+using TLS = vtkSMPThreadLocal<BoundsArray>;
+
+struct BoundsFunctor
+{
+ vtkFloatArray* Pts;
+ BoundsArray Bounds;
+ TLS LocalBounds;
+
+ BoundsFunctor(vtkFloatArray *pts) : Pts(pts) {}
+
+ // Initialize thread local storage
+ void Initialize()
+ {
+ // The first call to .Local() will create the array,
+ // all others will return the same.
+ std::array<double,6>& bds = this->LocalBounds.Local();
+ bds[0] = VTK_DOUBLE_MAX;
+ bds[1] = -VTK_DOUBLE_MAX;
+ bds[2] = VTK_DOUBLE_MAX;
+ bds[3] = -VTK_DOUBLE_MAX;
+ bds[4] = VTK_DOUBLE_MAX;
+ bds[5] = -VTK_DOUBLE_MAX;
+ }
+
+ // Process the range of points [begin,end)
+ void operator()(vtkIdType begin, vtkIdType end)
+ {
+ BoundsArray& lbounds = this->LocalBounds.Local();
+ float* x = this->Pts->GetPointer(3*begin);
+ for (vtkIdType i=begin; i<end; i++)
+ {
+ lbounds[0] = (x[0] < lbounds[0] ? x[0] : lbounds[0]);
+ lbounds[1] = (x[0] > lbounds[1] ? x[0] : lbounds[1]);
+ lbounds[2] = (x[1] < lbounds[2] ? x[1] : lbounds[2]);
+ lbounds[3] = (x[1] > lbounds[3] ? x[1] : lbounds[3]);
+ lbounds[4] = (x[2] < lbounds[4] ? x[2] : lbounds[4]);
+ lbounds[5] = (x[2] > lbounds[5] ? x[2] : lbounds[5]);
+
+ x += 3;
+ }
+ }
+
+ // Composite / combine the thread local storage into a global result.
+ void Reduce()
+ {
+ this->Bounds[0] = VTK_DOUBLE_MAX;
+ this->Bounds[1] = -VTK_DOUBLE_MAX;
+ this->Bounds[2] = VTK_DOUBLE_MAX;
+ this->Bounds[3] = -VTK_DOUBLE_MAX;
+ this->Bounds[4] = VTK_DOUBLE_MAX;
+ this->Bounds[5] = -VTK_DOUBLE_MAX;
+
+ using TLSIter = TLS::iterator;
+ TLSIter end = this->LocalBounds.end();
+ for (TLSIter itr = this->LocalBounds.begin(); itr != end; ++itr)
+ {
+ BoundsArray& lBounds = *itr;
+ this->Bounds[0] = (this->Bounds[0] < lBounds[0] ? this->Bounds[0] : lBounds[0]);
+ this->Bounds[1] = (this->Bounds[1] > lBounds[1] ? this->Bounds[1] : lBounds[1]);
+ this->Bounds[2] = (this->Bounds[2] < lBounds[2] ? this->Bounds[2] : lBounds[2]);
+ this->Bounds[3] = (this->Bounds[3] > lBounds[3] ? this->Bounds[3] : lBounds[3]);
+ this->Bounds[4] = (this->Bounds[4] < lBounds[4] ? this->Bounds[4] : lBounds[4]);
+ this->Bounds[5] = (this->Bounds[5] > lBounds[5] ? this->Bounds[5] : lBounds[5]);
+ }
+ }
+}; // BoundsFunctor
+```
+Then to use the functor:
+```
+ vtkFloatArray* ptsArray = vtkFloatArray::SafeDownCast(pts->GetData());
+ BoundsFunctor calcBounds(ptsArray);
+ vtkSMPTools::For(0, numPts, calcBounds);
+ std::array<double,6>& bds = calcBounds.Bounds;
+```
+
+A few things to note here:
+* LocalBounds.Local() will return a new instance of a `std::vector<std::vector<double>>` per thread the first time it is called by that thread. All calls afterwards will return the same instance for that thread. Therefore, threads can safely access the local object over and over again without worrying about race conditions.
+* The `Initialize()` method initializes the new instance of the thread local vector with invalid bound values.
+
+So at the end of the threaded computation, the `LocalBounds` will contain a number of arrays, each that was populated by one thread during the parallel execution. These still need to be composited to produce the global bounds. This can be achieved by iterating over all thread local values and combining them in the `Reduce()` method as shown previously. Consequently the user can simply retrieve the final bounds by accessing `calcBounds.Bounds` once `vtkSMPTools::For()` completes execution. Note that, if the methods exist, `Initialize()` and `Reduce()` are invoked automatically by `vtkSMPTools::For()`.
+
+Very important note: if you use more than one thread local storage object, don’t assume that the iterators will traverse them in the same order. The iterator for one may return the value from thread i with begin() whereas the other may return the value form thread j. If you need to store and access values together, make sure to use a struct or class to group them.
+
+Thread local objects are immensely useful. Often, visualization algorithms want to accumulate their output by appending to a data structure. For example, the contour filter iterates over cells and produces polygons that it adds to an output vtkPolyData. This is usually not a thread safe operation. One way to address this is to use locks that serialize writing to the output data structure.
+
+However, mutexes have a major impact on the scalability of parallel operations. Another solution is to produce a different vtkPolyData for each execution of the functor. However, this can lead to hundreds if not thousands of outputs that need to be merged, which is a difficult operation to scale. The best option is to use one vtkPolyData per thread using thread local objects. Since it is guaranteed that thread local objects are accessed by one thread at a time (but possibly in many consecutive functor invocations), it is thread safe for functors to keep adding polygons to these objects. The result is that the parallel section will produce only a few vtkPolyData, usually the same as the number of threads in the pool. It is much easier to efficiently merge these vtkPolyData.
+
+### Atomic Integers
+As mentioned previously, atomics should be represented by the C++ std::atomic<>. However, to provide a brief explanation of the importance of atomics we provide the following simple example.
+
+```
+int Total = 0;
+std::atomic<vtkTypeInt32> TotalAtomic(0);
+constexpr int Target = 1000000;
+constexpr int NumThreads = 2;
+
+VTK_THREAD_RETURN_TYPE MyFunction(void *)
+{
+ for (int i=0; i<Target/NumThreads; i++)
+ {
+ ++Total;
+ ++TotalAtomic;
+ }
+ return VTK_THREAD_RETURN_VALUE;
+}
+
+// Now exercise atomics
+vtkNew<vtkMultiThreader> mt;
+mt->SetSingleMethod(MyFunction, NULL);
+mt->SetNumberOfThreads(NumThreads);
+mt->SingleMethodExecute();
+std::cout << Total << " " << TotalAtomic.load() << endl;
+```
+
+When this program is executed, most of the time `Total` will be different (smaller) than `Target` whereas `TotalAtomic` will be exactly the same as `Target`. For example, a test run on a Mac prints: `999982 1000000`. This is because when the integer is not atomic, both threads can read the same value of `Total`, increment and write out the same value, which leads to losing one increment operation. Whereas, when ++ happens atomically, it is guaranteed that it will read, increment and write out `Total` all in one uninterruptible operation. When atomic operations are supported at hardware level, they are very fast.
+
+## Tips
+In this section, we provide some tips that we hope will be useful to those that want to develop shared memory parallel algorithms.
+
+### Think about Thread Safety
+First things first, it is essential to keep thread safety in mind. If the parallel section does not produce correct results consistently, there is not a lot of point in the performance improvement it produces. To create thread-safe algorithms, consider using common parallel design patterns. Also verify that the API you are using is thread safe under your particular application. While VTK continues to add additional thread-safe capabilities, there are still many booby traps to avoid.
+
+### Analysis Tools Are Your Friend
+The LLVM/Clang-based ThreadSanitizer is widely used to detect data races. Valgrind’s Helgrind is also a wonderful tool. Use these tools often. We developed the original backends mainly using Helgrind. Note that backends like TBB can produce many false positives; you may want to try different backends to reduce these. There are commercial tools with similar functionality, e.g., Intel’s Parallel Studio has static and dynamic checking.
+
+### Debugging Tricks
+Beyond using the analysis tools mentioned previously (e.g., ThreadSanitizer), there are some simple tricks that can be used to resolve programming issues relatively quickly. Firstly, switch between different backends. For example, if a program runs correctly when the backend is set to Sequential, but incorrectly when the backend is other than Sequential, it's likely that there is a race condition. Such broken code, when run repeatedly, while not always failing at the same point due to the variability of thread execution, will often fail at or near the same function, providing clues as to the location of the race. Also, empirically the STDThread backend seems to be most sensitive to race conditions. So make sure to test with more than one backend especially STDThread.
+
+### Avoid Locks
+Mutexes are expensive. Avoid them as much as possible. Mutexes are usually implemented as a table of locks by the kernel. They take a lot of CPU cycles to acquire. Specially, if multiple threads want to acquire them in the same parallel section. Use atomic integers if necessary. Try your best to design your algorithm without modifying the same data concurrently.
+
+### Use Atomics Sparingly
+Atomics are very useful and much more efficient that mutexes. However, overusing them may lead to performance issues. Try to design your algorithm in a way that you avoid locks and atomics. This also applies to using VTK classes that manipulate atomic integers such as MTime and reference count. Try to minimize operations that cause MTime or shared reference counts to change in parallel sections.
+
+### Grain Can Be Important
+In some situation, setting the right value for grain may be important. TBB does a decent job with this but there are situations where it can’t do the optimal thing. There are a number of documents on setting the grain size with TBB on the Web. If you are interested in tuning your code further, we recommend taking a look at some of them.
+
+### Minimize Data Movement
+This is true for serial parts of your code too but it is specially important when there are bunch of threads all accessing main memory. This can really push the limits of the memory bus. Code that is not very intensive computationally compared to how much memory it consumes is unlikely to scale well. Good cache use helps of course but may not be always sufficient. Try to group work together in tighter loops.
+
+### Choose Computation over Memory
+As mentioned earlier in this document, typically computation is much cheaper than data movement. As a result, it's a good idea to create compact data structures with minimal representational fat. Such data structures may require computation to extract important information: for example, a data structure that contains a vector 3-tuple need not represent the vector magnitude since this can be quickly computed. Depending on the number of times vector magnitude is needed, the cost of computing it is usually less than the cost of placing vector magnitude into memory. Of course, effects like this are a function of scale / data size and must be considered when designing applications.
+
+### Multi-Pass Implementations
+Parallel algorithms often require significant bookkeeping to properly partition and transform input data to output data. Trivial algorithms, such as mapping an input vector array of 3-tuples to an output scalar array of vector magnitudes, are easy to partition and map: for each vector tuple, a single scalar is produced; and if there are N tuples, there are N scalars. However, more complex algorithms such as building cell links (creating lists of cells connected to a point) or smoothing stencils (identifying points connected to each other via a cell edge) require an initial pass to determine the size of output arrays (and then to allocate the output), followed by another pass to actually populate the output arrays. While at first counterintuitive, it turns out that allocating a small number of large memory blocks is much, much faster than many dynamic allocations of small amounts of memory. This is one reason that a common implementation pattern for parallel algorithms is to use multiple data processing passes consisting of simple computing operations. Such an approach is quite different than many serial algorithms that often perform multiple, complex algorithmic steps for each input data item to be processed.
+
+A variation of this approach is to use thread local storage to perform computation on a local range of input, store the result in thread local, and then reduce/composite the local storage into the global output. While this is problematic for many reasons (especially since data movement is needed to composite the output data), it still can be used to effectively partition and transform input data to the output, especially if the thread local storage is relatively small in size.
+
+Whatever approach is used, parallel algorithms are often implemented using multiple passes. When designing parallel algorithms, it is important to think in terms of passes, and implement algorithms accordingly.
+
+### Use Parallel Design Patterns
+There are many parallel operations that are used repeatedly. Of course `for` loops and `fill()` are two obvious operations, but the `sort()` operation is more widely used than might be expected. Another is the prefix sum (or inclusive scan, or simply scan) typically used to build indices into data arrays. Become familiar with these and other parallel operations and the task of designing and implementing algorithms will be much easier.
+
+## Parallel Is Not Always Faster
+Threading introduces overhead into computation. As a result, threaded computation is not always faster than an equivalent serial operation. For example, `for` loops across a small number of data items can easily slow down computation due to **thread creation overhead**. A simple addition on each entry of an array may become a bottleneck if done using a too fine grain, due to **false sharing** (threads continuously invalidating other thread's cache). Even complex operations such as prefix sums across large amounts of data may be slower than serial implementations because of **synchronization issues**. For this reason, use threading sparingly to address data or computation of large scale. In VTK it is not uncommon to see code that switches between serial and parallel implementations based on input data size.
+
+Different backends may have significantly performance characteristics as well. TBB for example uses a thread pool combined with task stealing to address load balancing challenges. Empirically at the time of writing, in some situations TBB can significantly outperform the STDThread backend especially in situations where task loads are highly variable. Of course this may change as std::thread implementations mature and evolve.
diff --git a/Documentation/docs/developers_guide/git/.gitignore b/Documentation/docs/developers_guide/git/.gitignore
index c7b27663c128743e5c8607df89f40d987b210428..bc4a8905016bdcf658d33c711faaba1a8966d251 100644
--- a/Documentation/docs/developers_guide/git/.gitignore
+++ b/Documentation/docs/developers_guide/git/.gitignore
@@ -1,6 +1,3 @@
# generated by conf.py
-test.md
-develop.md
-develop_quickstart.md
thirdparty.md
thirdparty-projects.md
diff --git a/Documentation/docs/developers_guide/git/README.md b/Documentation/docs/developers_guide/git/README.md
index cfeda9fd7af8440c96383ef6a7ada4fd6ea20f48..21b7c4b18d5fb9234204c65dae75f9f5865304c8 100644
--- a/Documentation/docs/developers_guide/git/README.md
+++ b/Documentation/docs/developers_guide/git/README.md
@@ -2,6 +2,40 @@
orphan: true
---
-```{include} ../../../dev/git/README.md
-:relative-docs: .
-```
+VTK Git Usage
+=============
+
+VTK version tracking and development is hosted by [Git](http://git-scm.com).
+Please select a task for further instructions:
+
+Main Tasks
+----------
+* [Install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+ Git 1.7.2 or greater is preferred (required for development)
+
+* [Download VTK](download.md) - Users start here
+
+* [Develop VTK](develop.md) - Contributors start here
+
+Other Tasks
+-----------
+
+* [Review Changes](https://gitlab.kitware.com/vtk/vtk/-/merge_requests) -
+ VTK GitLab Merge Requests
+
+* [Test VTK](dashboard.md) - CDash client setup
+
+* [Learn Git](http://public.kitware.com/Wiki/Git/Resources) -
+ Third-party documentation
+
+Branches
+--------
+
+The upstream VTK repository has the following branches:
+
+* `master`: Development (default)
+* `release`: Maintenance of latest release
+* `nightly-master`: Follows `master`, updated at `01:00 UTC`
+* `hooks`: Local commit hooks
+ ([placed](http://public.kitware.com/Wiki/Git/Hooks#Local) in `.git/hooks`)
+* `dashboard`: Dashboard script ([setup](dashboard.md) a CDash client)
diff --git a/Documentation/docs/developers_guide/git/dashboard.md b/Documentation/docs/developers_guide/git/dashboard.md
index faff643d5085c9a69d3cf04c66f933a832c32205..796c45c10e63db5472cfd0afd6cf3f8b4a083053 100644
--- a/Documentation/docs/developers_guide/git/dashboard.md
+++ b/Documentation/docs/developers_guide/git/dashboard.md
@@ -1,3 +1,48 @@
-```{include} ../../../dev/git/dashboard.md
-:relative-docs: .
-```
+Dashboard Scripts
+=================
+
+This page documents how to use the VTK `dashboard` branch in [Git][].
+See the [README](README.md) for more information.
+
+[Git]: http://git-scm.com
+
+Using the Dashboard Scripts
+---------------------------
+
+The `dashboard` branch contains a dashboard client helper script.
+Use these commands to track it:
+
+ $ mkdir -p ~/Dashboards/VTKScripts
+ $ cd ~/Dashboards/VTKScripts
+ $ git init
+ $ git remote add -t dashboard origin https://gitlab.kitware.com/vtk/vtk.git
+ $ git pull origin
+
+The `vtk_common.cmake` script contains setup instructions in its
+top comments.
+
+Update the `dashboard` branch to get the latest version of this
+script by simply running:
+
+ $ git pull
+
+Here is a link to the script as it appears today: [vtk_common.cmake][].
+
+[vtk_common.cmake]: https://gitlab.kitware.com/vtk/vtk/-/tree/dashboard/vtk_common.cmake
+
+Changing the Dashboard Scripts
+------------------------------
+
+If you find bugs in the hooks themselves or would like to add new features,
+the can be edited in the usual Git manner:
+
+ $ git checkout -b my-topic-branch
+
+Make your edits, test it, and commit the result. Create a patch file with:
+
+ $ git format-patch origin/dashboard
+
+And post the results in the [Development][] category in the [VTK Discourse][] forum.
+
+[Development]: https://discourse.vtk.org/c/development
+[VTK Discourse]: https://discourse.vtk.org/
diff --git a/Documentation/docs/developers_guide/git/deprecation.md b/Documentation/docs/developers_guide/git/deprecation.md
index f0f5ea7154bfaca569f9d0ada8a8f99c64cb8d68..7b95657676099982139400fd7c302d01882f4b68 100644
--- a/Documentation/docs/developers_guide/git/deprecation.md
+++ b/Documentation/docs/developers_guide/git/deprecation.md
@@ -1,2 +1,77 @@
-```{include} ../../../dev/git/deprecation.md
+Deprecation Process
+===================
+
+This page documents how to deprecate an API and mark it as no longer necessary
+for downstream consumers of VTK.
+
+Deprecating classes and methods
+-------------------------------
+
+Classes, functions, and methods may be deprecated using the deprecation macros.
+
+```c++
+#include "vtkDeprecation.h" // Include the macros.
+
+// A deprecated class.
+VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation")
+class oldClass {
+public:
+ // A deprecated method.
+ VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation")
+ void oldMethod();
+};
+
+// A deprecated function.
+VTK_DEPRECATED_IN_X_Y_Z("reason for deprecation")
+void oldFunction();
```
+
+The `X_Y_Z` should be the newest macro available in the `vtkDeprecation.h`
+header when the API is added.
+
+Note that, unlike, the old `VTK_LEGACY_REMOVE` mechanism, the APIs are not
+deleted. This does interfere with various kinds of deprecations.
+
+ - *Changing the return type*: Don't do this. Use a new name for the
+ function/method.
+ - *Deprecating macros*: Use `VTK_LEGACY_REMOVE`. New macro APIs should be
+ highly discouraged.
+
+### Lifetime of deprecated APIs
+
+Deprecated APIs should exist for at least one release with the deprecation
+warning active. This gives consumers of VTK at least one cycle to notice the
+deprecation and move off of it.
+
+Upon branching for a release, `master` will soon after have all instances of
+deprecated symbols removed.
+
+### Avoiding warnings within VTK
+
+VTK is providing the deprecated symbols and as such may still use them in tests
+or implementations. Since these generate warnings when compiling VTK itself,
+classes which define deprecated symbols must suppress them.
+
+Sources which continue to use the deprecated macros should add a comment to the
+top of the source file to hide deprecation warnings in CI.
+
+```c++
+// Hide VTK_DEPRECATED_IN_X_Y_Z() warnings for this class.
+#define VTK_DEPRECATION_LEVEL 0
+```
+
+If one already exists, please add another comment to it so that when deprecated
+symbols are removed, it shows up in the search.
+
+Using `VTK_DEPRECATION_LEVEL`
+-----------------------------
+
+When using VTK, the `VTK_DEPRECATION_LEVEL` macro may be set to a version
+number. APIs which have been deprecated after this point will not fire (as the
+API is not deprecated as of the level requested). It should be defined using
+the `VTK_VERSION_CHECK(major, minor, patch)` macro.
+
+Note that APIs on the verge of deletion (those deprecated in at least one
+release) will always raise deprecation warnings.
+
+If not set, its value defaults to the current level of VTK.
diff --git a/Documentation/dev/git/develop.md b/Documentation/docs/developers_guide/git/develop.md
similarity index 99%
rename from Documentation/dev/git/develop.md
rename to Documentation/docs/developers_guide/git/develop.md
index cd17e21d46a4e6e2bf86e5e974e44838db82b8de..ce51fdb5b29381848ddae57e9ddbf736bfadc2fc 100644
--- a/Documentation/dev/git/develop.md
+++ b/Documentation/docs/developers_guide/git/develop.md
@@ -13,7 +13,7 @@ Here we document procedures used by the VTK development community.
In the interest of simplicity and brevity we do *not* provide an
explanation of why we use this approach.
-For a quickstart guide see [here](develop_quickstart.md)
+For a quickstart guide see [here](../develop_quickstart.md)
Workflow
--------
@@ -94,7 +94,7 @@ A reader should have a general idea of the feature or fix to be developed given
Caveats:
* To add data follow [these instructions](test.md#add-data).
- * If your change modifies third party code, see [Updating Third Party Projects](/ThirdParty/UPDATING.md).
+ * If your change modifies third party code, see [Updating Third Party Projects](thirdparty.md).
* To deprecate APIs, see [Deprecation Process](deprecation.md).
Guidelines for Commit logs
diff --git a/Documentation/docs/developers_guide/git/download.md b/Documentation/docs/developers_guide/git/download.md
index 951a7e556395a18c66afc3749271ae29e3a70b91..78019ea2f070c54059d8b7c315813f242c35799c 100644
--- a/Documentation/docs/developers_guide/git/download.md
+++ b/Documentation/docs/developers_guide/git/download.md
@@ -2,5 +2,54 @@
orphan: true
---
-```{include} ../../../dev/git/download.md
-```
+Download VTK with Git
+=====================
+
+This page documents how to download VTK source code through [Git][].
+See the [README](README.md) for more information.
+
+[Git]: http://git-scm.com
+
+Clone
+-----
+
+Clone VTK using the commands:
+
+ $ git clone https://gitlab.kitware.com/vtk/vtk.git VTK
+ $ cd VTK
+ $ git submodule update --init
+
+Update
+------
+
+Users that have made no local changes and simply want to update a
+clone with the latest changes may run:
+
+ $ git pull
+
+Avoid making local changes unless you have read our [developer instructions][].
+
+[developer instructions]: develop.md
+
+Release
+-------
+
+After cloning your local repository will be configured to follow the upstream
+`master` branch by default. One may create a local branch to track the
+upstream `release` branch instead, which should guarantee only bug fixes to
+the functionality available in the latest release:
+
+ $ git checkout --track -b release origin/release
+
+This local branch will always follow the latest release.
+Use the [above instructions](#update) to update it.
+Alternatively one may checkout a specific release tag:
+
+ $ git checkout v6.2.0
+
+Release tags never move. Repeat the command with a different tag to get a
+different release. One may list available tags:
+
+ $ git tag
+
+and then checkout any tag listed.
diff --git a/Documentation/dev/git/test.md b/Documentation/docs/developers_guide/git/test.md
similarity index 97%
rename from Documentation/dev/git/test.md
rename to Documentation/docs/developers_guide/git/test.md
index 0c4bdcba3ddd16a41251d0aaebbb8e790659bc98..46c5e6d745f27a45be6fe886060519acf2a8a671 100644
--- a/Documentation/dev/git/test.md
+++ b/Documentation/docs/developers_guide/git/test.md
@@ -10,12 +10,12 @@ Setup
-----
The workflow below depends on local hooks to function properly.
-Follow the main [developer setup instructions](develop_quickstart.md#initial-setup)
+Follow the main [developer setup instructions](../develop_quickstart.md#initial-setup)
before proceeding. In particular, run [SetupForDevelopment.sh][]:
$ ./Utilities/SetupForDevelopment.sh
-[SetupForDevelopment.sh]: /Utilities/SetupForDevelopment.sh
+[SetupForDevelopment.sh]:../../../../Utilities/SetupForDevelopment.sh
Workflow
--------
@@ -307,7 +307,7 @@ For example:
$ cat Some/Module/Testing/Data/Baseline/MyTest.png.sha512
477e6028...
-[vtkExternalData.cmake]: /CMake/vtkExternalData.cmake
+[vtkExternalData.cmake]: ../../../../CMake/vtkExternalData.cmake
#### Recover Data File ####
@@ -336,7 +336,7 @@ it to the project history. For example:
$ git cat-file blob refs/data/SHA512/477e6028... | sha512sum
477e6028... -
-[pre-commit]: /Utilities/Scripts/pre-commit
+[pre-commit]:../../../../Utilities/Scripts/pre-commit
### git gitlab-push ###
@@ -366,7 +366,7 @@ For VTK, that location is currently
complete SHA512 hash stored in the content link file (e.g., the text in
`MyTest.png.sha512`).
-[git-gitlab-push]: /Utilities/GitSetup/git-gitlab-push
+[git-gitlab-push]:../../../../Utilities/GitSetup/git-gitlab-push
### Publishing Data for an External Branch ###
diff --git a/Documentation/docs/developers_guide/release_process.md b/Documentation/docs/developers_guide/release_process.md
index 19cd8d6721e3649e3fd51387978f4412a273f70c..3ca63e73590960f241b7e7d8a6c3276c716b4fb1 100644
--- a/Documentation/docs/developers_guide/release_process.md
+++ b/Documentation/docs/developers_guide/release_process.md
@@ -1,2 +1,171 @@
-```{include} ../../dev/release_process.md
-```
+# Release Process
+
+This document provides a high-level overview of the VTK release cycle and
+associated release process.
+
+## Overview
+
+We aim to release a new version of VTK every six months. However, we recognize
+that this schedule is flexible. The project is funded and developed by many
+different groups, each of which works towards their own particular sets of
+features.
+
+VTK releases are named with a `Major.Minor.Patch` scheme.
+
+## Branching Scheme
+
+The overall release history resembles a skinny tree. Development proceeds along
+the `master` branch, consisting of topic branches that start from and are merged
+into `master`. Every so often, a release is tagged and branched from it.
+
+In general, no work takes place on the `release` branch, other than the handful
+of important patches that make up occasional patch releases.
+
+:::{hint}
+Steps for contributing changes specific to the `release` branch are documented in
+[](git/develop.md#create-a-topic).
+:::
+
+On the `master` branch, bug fixes and new features are continuously
+developed. At release time, the focus temporarily shifts to producing
+a library that is as stable and robust as possible.
+
+## Steps
+
+The process for cutting releases is as follows:
+
+1. Announce upcoming release
+
+ A few weeks before the intended `release` branch, announce on [VTK Discourse](https://discourse.vtk.org/)
+ that a new release is coming. This alerts developers to avoid making drastic
+ changes that might delay the release and gives them a chance to push important
+ and nearly completed features in time for the release. For example,
+ see [this post](https://discourse.vtk.org/t/vtk-9-2-0-release-cycle/8149).
+
+2. Polish the dashboards and bug tracker by addressing outstanding issue and
+ coordinate effort with relevant developers.
+
+ Persistent compilation and regression test problems are fixed. Serious
+ outstanding bugs are fixed.
+
+3. [Create a new issue](https://gitlab.kitware.com/vtk/vtk/-/issues/new) titled
+ `Release X.Y.Z[rcN]` based of the [new-release](https://gitlab.kitware.com/vtk/vtk/-/blob/master/.gitlab/issue_templates/new-release.md?plain=1) template.
+
+ :::{Important}
+ Specific steps to create eiter the candidate or the official release are found
+ in the newly created issue.
+ :::
+
+4. Perform the release candidate cycle
+
+ 1. Tag the release branch and create and publish release candidate
+ artifacts and change summaries.
+
+ 2. Announce the release candidate and request feedback from the
+ community, especially third-party packagers.
+
+ :::{hint}
+ Bug reports should be entered into the bug tracker with the upcoming
+ release number as the milestone.
+ :::
+
+ 3. If the community reports bugs, classify them in the bug tracker and ensure
+ they are fixed.
+
+ Only serious bugs and regressions need to be fixed before the release.
+ New features and minor problems should be merged into `master` as usual.
+
+ Patches for the release branch should start from the release branch, be
+ submitted through GitLab, and then merged into `master`. Once fully
+ tested there, the branch can be merged into the release branch.
+
+ When the selected issues are fixed in the release branch, tag the tip
+ of the release branch and release it as the next candidate, then the
+ cycle continues.
+
+ 4. Distribution specific patches can accumulate over time. Consider reviewing the
+ following distribution specific pages to identify potential fixes and improvements
+ that could be integrated in VTK itself:
+
+ * Debian:
+ - https://tracker.debian.org/pkg/vtk9
+ - https://udd.debian.org/patches.cgi?src=vtk9
+
+ * Gentoo:
+ - https://packages.gentoo.org/packages/sci-libs/vtk
+ - https://gitweb.gentoo.org/repo/gentoo.git/tree/sci-libs/vtk/files
+
+ * openSUSE:
+ - https://build.opensuse.org/package/show/openSUSE:Factory/vtk
+
+5. Package the official release
+
+ The official VTK package consists of tar balls and ZIP files of the source,
+ Python Wheels, Doxygen documentation, and regression test data, all at the
+ tag point.
+
+ Volunteer third-party packagers create binary packages from the official
+ release for various platforms, so their input is especially valuable during
+ the release cycle.
+
+ The release manager also compiles release notes for the official release
+ announcement. Release notes are compiled from various [standardized topic documents](https://gitlab.kitware.com/vtk/vtk/-/tree/master/Documentation/release)
+ added to the `Documentation/release/dev` folder while features or issues
+ are fixed. The aggregation of these topic files is done manually and
+ results in the creation of a file named `Documentation/release/X.Y.md` for
+ the current release.
+
+## GitLab and Releases
+
+GitLab milestones are used for keeping track of branches for the release. They
+allow keeping track of issues and merge requests which should be "done" for
+the milestone to be considered complete.
+
+For each release (including release candidates), a milestone is created with a
+plausible due date. The milestone page allows for an easy overview of branches
+which need wrangling for a release.
+
+### Merge Requests
+
+Merge requests which need to be rebased onto the relevant release branch
+should be marked with the `needs-rebase-for-release` tag and commented on how
+the branch can be rebased properly:
+
+ This branch is marked for a release, but includes other commits in
+ `master`. Please either rebase the branch on top of the release branch and
+ remove the `needs-rebase-for-release` tag from the merge request:
+
+ ```sh
+ $ git rebase --onto=origin/release origin/master $branch_name
+ $ git gitlab-push -f
+ ```
+
+ or, if there are conflicts when using a single branch, open a new branch
+ and open a merge request against the `release` branch:
+
+ ```sh
+ $ git checkout -b ${branch_name}-release $branch_name
+ $ git rebase --onto=origin/release origin/master ${branch_name}-release
+ $ git gitlab-push
+ ```
+
+ Thanks!
+
+### Wrangling Branches
+
+Branches may be wrangled using the filters in the merge request page. Replace
+`$release` at the end with the relevant milestone name:
+
+ https://gitlab.kitware.com/vtk/vtk/-/merge_requests?state=all&milestone_title=$release
+
+The following states of a merge request indicate where they are in the flow:
+
+ - open for `master`: get into `master` first
+ - open for `release`: ensure it is already in `master`
+ - open with `needs-rebase-for-release` tag: wait for contributor to rebase
+ properly; ping if necessary
+ - `MERGED`: merge into `release`
+
+There is currently no good way of marking a branch that went towards `master`
+is also in `release` already since tags cannot be added to closed merge
+requests. Suggestions welcome :) .
diff --git a/Documentation/docs/developers_guide/testing.md b/Documentation/docs/developers_guide/testing.md
index 49f344f6ffb9579021211bb7ef7cf80a0406b3ab..34d16abce356511fbdf3a84de7a41ad1c2a8ce2d 100644
--- a/Documentation/docs/developers_guide/testing.md
+++ b/Documentation/docs/developers_guide/testing.md
@@ -1,3 +1,38 @@
-```{include} ../../dev/testing.md
-:relative-docs: .
-```
+# Regression Testing
+
+## Testing and dashboard submitter setup
+
+Regression testing in VTK takes the form of a set of programs, that are included in the VTK source code and enabled in builds configured through CMake to have the `VTK_BUILD_TESTING` flag turned on. Test pass/fail results are returned to CTest via a test program's exit code. VTK contains helper classes that do specific checks, such as comparing a produced image against a known valid one, that are used in many of the regression tests. Test results may be submitted to Kitware's CDash instance, were they will be gathered and displayed at <http://open.cdash.org/index.php?project=VTK>
+
+All proposed changes to VTK are automatically tested on Windows, Mac and Linux machines. All changes that are merged into the master branch are subsequently tested again by more rigorously configured Windows, Mac and Linux continuous dashboard submitters. After 9PM Eastern Time, the master branch is again tested by a wider set of machines and platforms. These results appear in the next day's page.
+
+At each step in the code integration path the developers who contribute and merge code are responsible for checking the test results to look for problems that the new code might have introduced. Plus signs in CDash indicate newly detected problems. Developers can correlate problems with contributions by logging in to CDash. Submissions that contain a logged in developer's change are highlighted with yellow dots.
+
+It is highly recommended that developers test changes locally before submitting them. To run tests locally:
+
+1. Configure with `VTK_BUILD_TESTING` set ON
+
+ The exact set of tests created depends on many configuration options. Tests in non-default modules are only tested when those modules are purposefully enabled, the smoke tests described in the Coding Style section above are enabled only when the python or Tcl interpreter is installed, tests written in wrapped languages are only enabled when wrapping is turned on, etc.
+
+1. Build.Â
+
+ VTK tests are only available from the build tree.
+
+1. Run ctest at the command line in the build directory or make the TESTING target in Visual Studio.
+
+ As ctest runs the tests it prints a summary. You should expect 90% of the tests or better to pass if your VTK is configured correctly. Detailed results (which are also printed if you supply a --V argument to ctest) are put into the Testing/Temporary directory. The detailed results include the command line that ctest uses to spawn each test. Other particularly useful arguments are:
+ ```bash
+ --R TestNameSubstringToInclude to choose tests by name
+
+ --E TestNameSubstringToExclude to reject tests by name
+
+ --I start,stop,step to run a portion of the tests
+
+ --j N to run N tests simultaneously.
+ ```
+
+Dashboard submitting machines work at a slightly higher level of abstraction that adds the additional stages of downloading, configuring and building VTK before running the tests, and submitting all results to CDash afterward. With a build tree in place you can run "ctest --D Experimental" to run at this level and submit the results to the experimental section of the VTK dashboard or "ctest --M Experimental -T Build --T Submit" etc to pick and choose from among the stages. When setting up a test submitter machine one should start with the experimental configuration and then, once the kinks are worked out, promote the submitter to the Nightly section.
+
+The volunteer machines use cron or Windows task scheduler to run CMake scripts that configure a VTK build with specific options, and then run ctest --D as above. Within CDash, you can see each test machine's specific configuration by clicking on the Advanced View and then clicking on the note icon in the Build Name column. This is a useful starting point when setting up a new submitter. It is important that each submitter's dashboard script include the name of the person who configures or maintains the machine so that, when the machine has problems, the dashboard maintainer can address it.
+
+For details about the Continuous Integration infrastructure hosted at Kitware see [here](git/develop.md#continuous-integration).
diff --git a/Documentation/docs/vtk_documentation.py b/Documentation/docs/vtk_documentation.py
index e067c83f62f722f08bc97367fa53f66c2f26f3e5..a7f7cf28620136801a67281f345e783401fb4a89 100644
--- a/Documentation/docs/vtk_documentation.py
+++ b/Documentation/docs/vtk_documentation.py
@@ -145,64 +145,6 @@ def add_init_file(path):
# -----------------------------------------------------------------------------------------
MANUAL_SUBSTITUTIONS = [
- {
- "source": "../dev/git/test.md",
- "destination": "./developers_guide/git/test.md",
- "substitutions": [
- (" /Utilities/", "../../../../Utilities/"),
- ("/CMake/", "../../../../CMake/"),
- ("develop_quickstart.md", "../develop_quickstart.md")
- ],
- },
- {
- "source": "../dev/git/develop.md",
- "destination": "./developers_guide/git/develop.md",
- "substitutions": [
- (" /Utilities/", "../../../../Utilities/"),
- ("/ThirdParty/UPDATING.md", "thirdparty.md"),
- ("/Documentation/dev/build.md", "../../build_instructions/index.md"),
- ("develop_quickstart.md", "../develop_quickstart.md")
- ],
- },
- {
- "source": "../dev/git/develop_quickstart.md",
- "destination": "./developers_guide/develop_quickstart.md",
- "substitutions": [
- (" /Utilities/", "../../../Utilities/"),
- ("/ThirdParty/UPDATING.md", "thirdparty.md"),
- ("/Documentation/dev/build.md", "../build_instructions/index.md"),
- ("develop.md", "./git/develop.md"),
- ("download.md", "./git/download.md"),
- ],
- },
- {
- "source": "../dev/build_wasm_emscripten.md",
- "destination": "./advanced/build_wasm_emscripten.md",
- "substitutions": [
- ("\(git/develop.md\)", "(../developers_guide/git/develop.md)"),
- ],
- },
- {
- "source": "../dev/build_for_mobile.md",
- "destination": "./advanced/build_for_mobile.md",
- "substitutions": [
- ("\(build.md\)", "(../build_instructions/build.md)"),
- ],
- },
- {
- "source": "../dev/build_python_wheels.md",
- "destination": "./advanced/build_python_wheels.md",
- "substitutions": [
- ("\(build.md\)", "(../build_instructions/build.md)"),
- ],
- },
- {
- "source": "../dev/build_documentation.md",
- "destination": "./advanced/build_documentation.md",
- "substitutions": [
- ("\(build.md\)", "(../build_instructions/build.md)"),
- ],
- },
{
"source": "../../ThirdParty/imported.md",
"destination": "./developers_guide/git/thirdparty-projects.md",