Update 3dtrees: py3dtiles to v1.1 (#1746)

kgerb · bgruening · web-flow · commit 48a2ce7a4d5d · 2026-01-09T18:19:50.000+01:00
* update tool to v1.1 - collection support

* fix linting issue

* fix min to count - issue (9 instead of 1)

* Update tools/3dtrees_py3dtiles/py3dtiles.xml

Co-authored-by: Björn Grüning &lt;bjoern@gruenings.eu&gt;

* update to support multiple = true instead of collections

---------

Co-authored-by: Björn Grüning &lt;bjoern@gruenings.eu&gt;
diff --git a/tools/3dtrees_py3dtiles/py3dtiles.xml b/tools/3dtrees_py3dtiles/py3dtiles.xml
@@ -1,18 +1,22 @@
-<tool id="3dtrees_py3dtiles" name="3Dtrees: Py3DTiles Converter" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@" profile="24.1">
-    <description>Convert LAZ point clouds to Cesium 3D Tiles with custom attribute support</description>
+<tool id="3dtrees_py3dtiles" name="3Dtrees: Py3DTiles Converter" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@" profile="24.2">
+    <description>Convert LAS/LAZ collection to Cesium 3D points_tiles</description>
     <macros>
-        <token name="@TOOL_VERSION@">1.0.0</token>
+        <token name="@TOOL_VERSION@">1.1.0</token>
         <token name="@VERSION_SUFFIX@">0</token>
     </macros>
     <requirements>
-        <container type="docker">ghcr.io/3dtrees-earth/3dtrees_py3dtiles:latest</container>
+        <container type="docker">ghcr.io/3dtrees-earth/3dtrees_py3dtiles:@TOOL_VERSION@</container>
     </requirements>
     <command detect_errors="exit_code"><![CDATA[
         export NUMBA_CACHE_DIR=\$TMPDIR &&
-        ln -s '$input' input.laz &&
+        mkdir -p input_files &&
+        mkdir -p tiles_output &&
+        #for $f in $input
+            ln -s '$f' input_files/'${f.element_identifier}.laz' &&
+        #end for
         python /src/run.py
-        --input input.laz
-        --output-dir src/tiles_output
+        --input input_files
+        --output-dir tiles_output
         #if $extra_fields
             --extra-fields '$extra_fields'
         #end if
@@ -22,27 +26,25 @@
         #if $overwrite
             --overwrite
         #end if
+        2>&1
         ]]>
     </command>
     <inputs>
-        <param name="input" type="data" format="laz" label="Point Cloud Dataset" help="LAS/LAZ point cloud file to convert to 3D Tiles"/>
-        <param name="extra_fields" type="text" optional="true" label="Extra Fields" help="Comma-separated list of extra fields to include in tiles (e.g., 'PredInstance' for segmentation visualization). Leave empty to include only standard fields."/>
-        <param name="srs_out" type="text" value="4978" label="Output CRS (EPSG code)" help="Output coordinate reference system. Default is 4978 (ECEF) for proper Cesium visualization. Leave empty to preserve original CRS."/>
-        <param name="overwrite" type="boolean" truevalue="true" falsevalue="false" checked="false" label="Overwrite existing output" help="Clear output directory before conversion if it already contains files"/>
+        <param name="input" type="data" format="laz" multiple="true" label="Point Cloud Collection" help="Collection of LAZ/LAS files to merge and convert to 3D Tiles" />
+        <param name="extra_fields" type="text" optional="true" label="Extra Fields" help="Comma-separated list of extra fields to include in tiles (e.g., 'PredInstance' for segmentation visualization). Leave empty to include only standard fields." />
+        <param name="srs_out" type="text" value="4978" label="Output CRS (EPSG code)" help="Output coordinate reference system. Default is 4978 (ECEF) for proper Cesium visualization. Leave empty to preserve original CRS." />        
+        <param name="overwrite" type="boolean" truevalue="true" falsevalue="false" checked="false" label="Overwrite existing output" help="Clear output directory before conversion if it already contains files" />
     </inputs>
     <outputs>
-        <!-- Root level: tileset.json metadata -->
-        <data name="tileset_json" format="json" label="tileset" from_work_dir="src/tiles_output/tileset.json"/>
-        <!-- Root level: preview.pnts thumbnail -->
-        <data name="preview_pnts" format="pnts" label="preview" from_work_dir="src/tiles_output/preview.pnts"/>
-        <!-- Points subdirectory: all r*.pnts tile files -->
+        <data name="tileset_json" format="json" label="tileset" from_work_dir="tiles_output/tileset.json"/>
+        <data name="preview_pnts" format="pnts" label="preview" from_work_dir="tiles_output/preview.pnts"/>
         <collection name="points_tiles" type="list" label="points">
-            <discover_datasets pattern="(?P&lt;designation&gt;r.*)\.pnts" directory="src/tiles_output" recurse="true" visible="false" format="pnts"/>
+            <discover_datasets pattern="(?P&lt;designation&gt;r.*)\.pnts" directory="tiles_output" recurse="true" visible="false" format="pnts"/>
         </collection>
     </outputs>
     <tests>
-        <test>
-            <param name="input" value="mikro.laz"/>
+        <test expect_num_outputs="3">
+            <param name="input" value="mikro.laz" ftype="laz"/>
             <param name="srs_out" value="4978"/>
             <output name="tileset_json" ftype="json" compare="contains">
                 <assert_contents>
@@ -51,9 +53,6 @@
                     <has_text text="asset"/>
                     <has_text text="version"/>
                     <has_text text="geometricError"/>
-                    <has_text text="preview.pnts"/>
-                    <has_text text="points/"/>
-                    <has_n_lines n="1"/>
                 </assert_contents>
             </output>
             <output_collection name="points_tiles" type="list" count="9"/>
@@ -63,21 +62,20 @@
 
 **What it does**
 
-This tool converts LAS/LAZ point cloud files to Cesium 3D Tiles format using py3dtiles. Unlike other tiling tools (e.g., gocesiumtiler), py3dtiles supports custom attributes, which is essential for visualizing segmentation results and other point cloud classifications.
+This tool converts a collection of LAS/LAZ point cloud files to a single Cesium 3D Tiles tileset using py3dtiles. 
 
-The tool automatically:
+**Key features:**
 
-1. Detects the coordinate reference system (CRS) from the input file
-2. Transforms coordinates to ECEF (EPSG:4978) for proper Cesium visualization if CRS is available
-3. Preserves custom attributes like segmentation IDs when specified
-4. Generates an optimized octree structure for efficient web visualization
-5. Post-processes tileset structure to fix potential URI path issues
+1. **Memory-efficient merging**: Uses streaming to merge multiple files with constant memory (~50MB) regardless of total dataset size
+2. **Custom attributes**: Supports extra point attributes like PredInstance for segmentation visualization
+3. **Automatic CRS transformation**: Transforms to ECEF (EPSG:4978) for proper Cesium visualization
+4. **Out-of-core processing**: py3dtiles handles large merged files efficiently
 
 -----
 
 **Input**
 
-- **Point Cloud Dataset**: LAS or LAZ format point cloud file
+- **Point Cloud Collection**: Collection of LAZ/LAS files (e.g., segmented outputs from the merge step)
 - **Extra Fields**: Optional comma-separated list of extra point attributes to include (e.g., "PredInstance" for instance segmentation)
 - **Output CRS**: EPSG code for output coordinates (default: 4978 for ECEF). Leave empty to keep original coordinates.
 - **Overwrite**: Clear output directory before conversion
@@ -86,44 +84,24 @@ The tool automatically:
 
 **Output**
 
-- **3D Tileset Metadata**: The main tileset.json file that describes the tile structure
-- **3D Tile Files**: Collection of binary tile files (.pnts format) containing the point cloud data
+- **tileset.json**: The main tileset metadata file
+- **preview.pnts**: Preview tile for quick loading
+- **points collection**: All tile files (.pnts format) containing the point cloud data
 
 The output can be directly hosted on a web server and visualized using CesiumJS.
 
 -----
 
-**Use Cases**
+**Workflow Integration**
 
-1. **Standard Visualization**: Convert standardized point clouds to 3D Tiles for web-based viewing
-2. **Segmentation Visualization**: Include custom attributes like "PredInstance" to visualize tree segmentation results
-3. **Custom Attributes**: Preserve any extra point attributes (e.g., quality scores, classifications) for specialized visualization
-
------
-
-**Technical Details**
-
-- **Coordinate Transformation**: Files with CRS metadata are automatically transformed to ECEF (EPSG:4978) for proper Cesium camera controls
-- **Files without CRS**: Coordinates are preserved as-is, assuming they're already in a suitable local/relative system
-- **Custom Attributes**: Full support for extra dimensional attributes via py3dtiles
-- **Format**: Generates Cesium 3D Tiles v1.0 with PNTS (Point Cloud) tiles
-
------
-
-**Comparison with gocesiumtiler**
-
-While gocesiumtiler is faster, py3dtiles is chosen for this workflow because:
-
-- Supports custom point attributes (essential for segmentation visualization)
-- Includes bug fixes for specific use cases
-- Better handling of coordinate transformations with pyproj
+In the EndToEndPipeline workflow, this tool receives the segmented LAZ collection from the merge step and produces a single unified 3D Tiles tileset for the entire dataset.
 
     </help>
     <creator>
         <organization name="3Dtrees-Team, University of Freiburg" url="https://github.com/3dTrees-earth"/>
     </creator>
     <citations>
-        <citation type="bibtex">@misc{py3dtiles title = {Py3DTiles: Python library for 3D Tiles}, author = {py3dtiles Contributors}, year = {2024}, url = {https://gitlab.com/py3dtiles/py3dtiles}}</citation>
+        <citation type="bibtex">@misc{py3dtiles, title = {Py3DTiles: Python library for 3D Tiles}, author = {py3dtiles Contributors}, year = {2024}, url = {https://gitlab.com/py3dtiles/py3dtiles}}</citation>
         <citation type="bibtex">
             @misc{3dtrees_py3dtiles, title = {3Dtrees: Py3DTiles}, author = {3Dtrees-Project}, year = {2025}}
         </citation>
