Other platforms bindings and renaming

.github/actions/conformance/action.yml

@@ -1,13 +1,15 @@
-# Checks a codec against fspm-TF's conformance files, in a codec's own CI, once the codec has run:
+# Checks a codec against encoding3d's conformance files, in a codec's own CI, once the codec has run:
 #
-#   - uses: ./.github/actions/conformance            (in this repository; elsewhere openalea/fspm-TF/.github/actions/conformance@main)
+#   - uses: ./.github/actions/conformance            (in this repository; elsewhere openalea/encoding3d/.github/actions/conformance@main)
 #     with:
 #       dumps: out/dumps          # what the codec read: one JSON dump per conformance GLB, x.json for x.expected.json
-#       written: out/written      # what the codec wrote: the conformance scenes, as .glb files (optional)
+#       written: out/written      # what the codec wrote: the conformance scenes, as .glb files (optional), and
+#                                 # archives (.fspm.zip) when the codec packs
+#       instances: "true"         # "false" for a codec reading 0.3 only: no instances (0.4) and archives
 #
-# Reading passes when every dump equals its expected values; writing, when every written file passes fspm-tf validate
-# and Khronos' glTF-Validator with no error.
-name: fspm-TF conformance
+# Reading passes when every dump equals its expected values (the dumps' layout: conformance/README.md); writing, when
+# every written file passes encoding3d validate and Khronos' glTF-Validator with no error.
+name: encoding3d conformance
 description: Compare a codec's reading of the conformance files with their expected values, and validate what it wrote
 inputs:
   dumps:
@@ -17,8 +19,12 @@ inputs:
     description: the folder of the .glb files the codec wrote for the conformance scenes (empty to skip)
     required: false
     default: ""
-  fspm-tf:
-    description: the path of an fspm-TF checkout (its conformance folder and Python package)
+  instances:
+    description: whether the codec reads 0.4's instances and archives (their dumps compared); "false" skips them
+    required: false
+    default: "true"
+  encoding3d:
+    description: the path of an encoding3d checkout (its conformance folder and Python package)
     required: false
     default: "."
   gltf-validator:
@@ -31,20 +37,23 @@ runs:
     - uses: actions/setup-python@v5
       with:
         python-version: "3.12"
-    - name: Install openalea.fspm_tf
+    - name: Install openalea.encoding3d
       shell: bash
-      run: python -m pip install numpy jsonschema "${{ inputs.fspm-tf }}"
+      run: python -m pip install numpy jsonschema "${{ inputs.encoding3d }}"
     - name: Reading
       shell: bash
-      run: fspm-tf compare-all "${{ inputs.dumps }}" "${{ inputs.fspm-tf }}/conformance"
-    - name: Writing, fspm-TF validator
+      run: encoding3d compare-all "${{ inputs.dumps }}" "${{ inputs.encoding3d }}/conformance" ${{ inputs.instances == 'false' && '--skip-instances' || '' }}
+    - name: Writing, encoding3d validator
       if: inputs.written != ''
       shell: bash
-      run: find "${{ inputs.written }}" -name "*.glb" -print0 | xargs -0 fspm-tf validate
+      run: find "${{ inputs.written }}" \( -name "*.glb" -o -name "*.fspm.zip" \) -print0 | xargs -0 encoding3d validate
     - name: Writing, Khronos' glTF-Validator
       if: inputs.written != '' && runner.os == 'Linux'
       shell: bash
       run: |
         curl -sSL -o validator.tar.xz "https://github.com/KhronosGroup/glTF-Validator/releases/download/${{ inputs.gltf-validator }}/gltf_validator-${{ inputs.gltf-validator }}-linux64.tar.xz"
         tar xf validator.tar.xz gltf_validator
-        find "${{ inputs.written }}" -name "*.glb" -print0 | xargs -0 -n1 ./gltf_validator
+        find "${{ inputs.written }}" -name "*.glb" -print0 | xargs -0 -n1 ./gltf_validator || {
+          # each file's issues are in its report beside it: print the errors
+          find "${{ inputs.written }}" -name "*.report.json" -exec python -c "import json, sys; report = json.load(open(sys.argv[1])); [print(sys.argv[1], m['code'], m.get('pointer', ''), m['message']) for m in report['issues']['messages'] if m['severity'] == 0]" {} \;
+          exit 1; }

.github/workflows/conda-build.yml

@@ -22,3 +22,14 @@ jobs:
     secrets:
       anaconda_token: ${{ secrets.ANACONDA_TOKEN }}
 
+  ci-ok:
+    name: CI OK
+    needs: build
+    if: always()          # run even if build failed/cancelled, otherwise it'd be "skipped" (= passes!)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check all OpenAlea CI jobs succeeded
+        run: |
+          echo "build result: ${{ needs.build.result }}"
+          [ "${{ needs.build.result }}" = "success" ]
+

.github/workflows/conformance.yml

@@ -1,4 +1,4 @@
-# The conformance files are valid glTF for every viewer (Khronos' glTF-Validator) and valid fspm-TF (our validator)
+# The conformance files are valid glTF for every viewer (Khronos' glTF-Validator) and valid encoding3d (our validator)
 name: Conformance
 
 on:
@@ -17,22 +17,24 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-      - name: Install openalea.fspm_tf (its dependencies, conda-only in pyproject.toml, given here), and VTK for the ParaView reader's tests
-        run: python -m pip install numpy jsonschema pytest vtk . 
+      - name: Install openalea.encoding3d (its dependencies, conda-only in pyproject.toml, given here), and VTK for the ParaView reader's tests
+        run: python -m pip install numpy jsonschema scipy pytest pyzmq vtk . 
       - name: Tests, the ParaView reader's conversion included
         run: pytest bindings/python/test -v
       - name: The committed files are the generated ones
         run: |
           python conformance/generate.py
-          git diff --exit-code -- conformance
-      - name: fspm-TF validator
-        run: fspm-tf validate conformance/*.glb conformance/growing_sequence/scene.fspm.json
+          # the evaluated values' last digits follow the platform's BLAS: test_conformance compares them within the
+          # protocol's 1e-12; every other file must be what the generator writes, byte for byte
+          git diff --exit-code -- conformance ':(exclude)conformance/instances/*.evaluated.json'
+      - name: encoding3d validator
+        run: encoding3d validate conformance/*.glb conformance/growing_sequence/scene.fspm.json conformance/instances/scene.fspm.json conformance/instances/embedded.glb conformance/archives/*.fspm.zip
       - name: Khronos glTF-Validator
         run: |
           curl -sSL -o validator.tar.xz "https://github.com/KhronosGroup/glTF-Validator/releases/download/${GLTF_VALIDATOR}/gltf_validator-${GLTF_VALIDATOR}-linux64.tar.xz"
           tar xf validator.tar.xz gltf_validator
-          for file in conformance/*.glb conformance/growing_sequence/*.glb; do
-            ./gltf_validator "$file" || exit 1
+          for file in conformance/*.glb conformance/growing_sequence/*.glb conformance/instances/*.glb conformance/instances/parts/*.glb; do
+            ./gltf_validator "$file" || { python -c "import json, sys; report = json.load(open(sys.argv[1])); [print(sys.argv[1], m['code'], m.get('pointer', ''), m['message']) for m in report['issues']['messages'] if m['severity'] == 0]" "${file}.report.json"; exit 1; }
           done
 
   docs:
@@ -42,10 +44,14 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-      - name: Install openalea.fspm_tf and the documentation's tools
-        run: python -m pip install numpy jsonschema sphinx pydata-sphinx-theme myst-parser sphinx-favicon sphinx-copybutton .
+      - name: Install openalea.encoding3d and the documentation's tools
+        run: |
+          sudo apt-get install -y pandoc
+          python -m pip install numpy jsonschema pytest sphinx ".[doc]"
+      - name: The notebooks run
+        run: python -m pytest --nbmake doc/notebooks tutorials/01_encoding3d_alone
       - name: Build the documentation, warnings as errors
-        run: python -m sphinx -b html docs docs/_build -W --keep-going
+        run: python -m sphinx -b html doc doc/_build -W --keep-going
 
   # The reference codec through the action other codecs use: its dumps of the conformance files, and the files it writes
   python-codec-conformance:
@@ -57,7 +63,7 @@ jobs:
           python-version: "3.12"
       - name: Dump and write the conformance scenes with the Python codec
         run: |
-          python -m pip install numpy jsonschema .
+          python -m pip install numpy jsonschema scipy .
           python bindings/python/conformance_run.py conformance out
       - uses: ./.github/actions/conformance
         with:

.github/workflows/cpp-codec.yml

@@ -0,0 +1,51 @@
+# The C++ codec (bindings/cpp): its tests on Linux, macOS and Windows; the conformance check other codecs run (its
+# dumps of the conformance files compared with their expected values, the files it writes validated); the coupling
+# conformance sessions. No platform: CPlantBox's adapter (bindings/cpp/cplantbox), a proposal for CPlantBox, is tested
+# by hand (bindings/cpp/cplantbox/README.md). OpenAlea's conda CI builds the Python package only.
+name: C++ codec
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure (nlohmann_json fetched)
+        run: cmake -S bindings/cpp -B build -DCMAKE_BUILD_TYPE=Release
+      - name: Build
+        run: cmake --build build --config Release
+      - name: Tests
+        run: ctest --test-dir build -C Release --output-on-failure
+
+  conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Dump and write the conformance scenes with the C++ codec
+        run: |
+          cmake -S bindings/cpp -B build -DCMAKE_BUILD_TYPE=Release
+          cmake --build build --target encoding3d_conformance_run
+          ./build/encoding3d_conformance_run conformance out
+      - uses: ./.github/actions/conformance
+        with:
+          dumps: out/dumps
+          written: out/written
+      # the coupling conformance sessions (specification §9, §11): the C++ participant, over ZeroMQ (libzmq) and a folder
+      - name: The coupling conformance sessions
+        run: |
+          sudo apt-get install -y -q libzmq3-dev
+          cmake -S bindings/cpp -B build -DCMAKE_BUILD_TYPE=Release
+          cmake --build build --target encoding3d_coupling_conformance
+          python -m pip install numpy jsonschema pyzmq .
+          encoding3d couple-conformance conformance/coupling --participant "$PWD/build/encoding3d_coupling_conformance"
+

.github/workflows/enforce-source-branch.yml

@@ -0,0 +1,19 @@
+name: Enforce source branch
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  check-source-branch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check PR source branch
+        run: |
+          if [ "${{ github.head_ref }}" != "develop" ]; then
+            echo "❌ PRs to main must originate from the 'develop' branch."
+            echo "   This PR is from: ${{ github.head_ref }}"
+            exit 1
+          fi
+          echo "✅ Source branch is 'develop'. OK."

.github/workflows/java-codec.yml

@@ -0,0 +1,53 @@
+# The Java codec (bindings/java): its tests on Linux, macOS and Windows; the conformance check other codecs run; the
+# coupling conformance sessions. No platform: GroIMP's adapter and plugin (bindings/java/groimp, groimp-plugin),
+# proposals for GroIMP, are tested by hand (their README.md). OpenAlea's conda CI builds the Python package only.
+name: Java codec
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+          cache: maven
+      - name: Tests, the conformance files included
+        run: mvn -B -f bindings/java/pom.xml verify
+
+  conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+          cache: maven
+      - name: Dump and write the conformance scenes with the Java codec
+        run: |
+          mvn -B -q -f bindings/java/pom.xml package -DskipTests dependency:copy-dependencies -DincludeScope=runtime
+          java -cp "bindings/java/target/encoding3d-0.1.0.jar:bindings/java/target/dependency/*" org.openalea.encoding3d.ConformanceRun conformance out
+      - uses: ./.github/actions/conformance
+        with:
+          dumps: out/dumps
+          written: out/written
+      # the coupling conformance sessions (specification §9, §11): the Java participant, over ZeroMQ (JeroMQ) and a folder
+      - name: The coupling conformance sessions
+        run: |
+          python -m pip install pyzmq
+          encoding3d couple-conformance conformance/coupling --participant \
+            "java -cp $PWD/bindings/java/target/encoding3d-0.1.0.jar:$PWD/bindings/java/target/dependency/* org.openalea.encoding3d.coupling.ConformanceParticipant"
+

.github/workflows/julia-codec.yml

@@ -0,0 +1,86 @@
+# The Julia codec (bindings/julia/encoding3d): its tests, on the oldest supported Julia and the latest release, and the
+# conformance check other codecs run (its dumps of the conformance files compared with their expected values, the files
+# it writes validated by encoding3d validate and Khronos' glTF-Validator); its coupling participant. No platform: the
+# package extensions for VirtualPlantLab (PlantGraphs, PlantGeomTurtle) and MTG.jl, proposals for those platforms, are
+# tested by hand in their own projects (test/plantgraphs, test/multiscaletreegraph; bindings/julia/README.md). OpenAlea's
+# conda CI builds the Python package only.
+name: Julia codec
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    name: Julia ${{ matrix.julia-version }}, ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        julia-version: ["1.10", "1"]
+        os: [ubuntu-latest]
+        include:
+          - julia-version: "1"
+            os: windows-latest
+          - julia-version: "1"
+            os: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ matrix.julia-version }}
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+        with:
+          project: bindings/julia/encoding3d
+      - uses: julia-actions/julia-runtest@v1
+        with:
+          project: bindings/julia/encoding3d
+
+  conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: "1"
+      - uses: julia-actions/cache@v2
+      - name: Dump and write the conformance scenes with the Julia codec
+        run: |
+          julia --project=bindings/julia/encoding3d -e 'using Pkg; Pkg.instantiate()'
+          julia --project=bindings/julia/encoding3d bindings/julia/conformance_run.jl conformance out
+      - uses: ./.github/actions/conformance
+        with:
+          dumps: out/dumps
+          written: out/written
+
+  # encoding3d.jl as a participant of coupling sessions run by the Python coordinator (specification §11), over ZeroMQ
+  # and over a folder
+  coupling:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: "1"
+      - uses: julia-actions/cache@v2
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: The Python coordinator
+        run: pip install -e . numpy pytest pyzmq jsonschema
+      - name: A Julia project with encoding3d and ZMQ
+        run: |
+          mkdir -p coupling-env
+          julia --project=coupling-env -e 'using Pkg; Pkg.develop(path="bindings/julia/encoding3d"); Pkg.add("ZMQ")'
+      - name: The coupling tests, with the Julia participant
+        env:
+          ENCODING3D_JULIA: julia --project=coupling-env
+        run: pytest -v bindings/python/test/test_coupling.py
+      - name: The coupling conformance sessions, the Julia participant
+        run: |
+          julia --project=coupling-env -e 'using Pkg; Pkg.add("JSON")'
+          encoding3d couple-conformance conformance/coupling --participant \
+            "julia --project=$PWD/coupling-env $PWD/bindings/julia/coupling_conformance.jl"

.gitignore

@@ -18,6 +18,7 @@ env/
 downloads/
 eggs/
 parts/
+!conformance/instances/parts/
 bin/
 var/
 sdist/
@@ -111,10 +112,14 @@ test/*.png
 examples/**/outputs/
 
 /dev*.md
+/.devplan/
 
 # glTF-Validator reports
 *.report.json
 
 # the documentation build, and its pages generated from spec/vocabulary
-docs/_build/
-docs/_generated/
+doc/_build/
+doc/_generated/
+
+# Julia: environments resolved locally (the codec is a library: no committed manifest)
+bindings/julia/**/Manifest*.toml

.readthedocs.yml

@@ -9,4 +9,4 @@ conda:
   environment: conda/environment.yml
 
 sphinx:
-  configuration: docs/conf.py
+  configuration: doc/conf.py