ENH: improve gltf handling

- scene

  - write with fileName, additional getMesh accessor

  - addColourToMesh accepts an alpha field size 1 as a constant
    alpha value

  - sceneWriter wrapper

ENH: improve gltf handling of colour and alpha specification

- accept plain input directly.
  Eg,
      colour  (1 0 1);
  vs
      colour      uniform;
      colourValue (1 0 1);

- use field magnitude for colouring of non-scalar fields.

  Eg, having three different colour maps for a vector field simply
  does not help much with visualisation.

src/fileFormats/Make/files

@@ -36,6 +36,7 @@ gltf/foamGltfBufferView.C
 gltf/foamGltfMesh.C
 gltf/foamGltfObject.C
 gltf/foamGltfScene.C
+gltf/foamGltfSceneWriter.C
 
 starcd/STARCDCore.C
 stl/STLCore.C

src/fileFormats/colours/colourTable.H

@@ -178,7 +178,7 @@ public:
         //- Predefined tables
         static const HashPtrTable<colourTable>& tables();
 
-        //- Return the colour at x (within 0-1 range)
+        //- Return the colour at x. The input is clipped to 0-1 range.
         vector value(const scalar x) const;
 
         //- Return a discrete lookup table of colours

src/fileFormats/gltf/foamGltfFwd.H

@@ -0,0 +1,54 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | www.openfoam.com
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+    Copyright (C) 2022 OpenCFD Ltd.
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+Description
+    Forward declarations for exposed glTF interfaces
+
+\*---------------------------------------------------------------------------*/
+
+#ifndef Foam_gltf_Forward_Declarations_H
+#define Foam_gltf_Forward_Declarations_H
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+namespace Foam
+{
+namespace glTF
+{
+
+// Forward Declarations
+class scene;
+class sceneWriter;
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+} // End namespace glTF
+} // End namespace Foam
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+#endif
+
+// ************************************************************************* //

src/fileFormats/gltf/foamGltfObjectTemplates.C

@@ -28,15 +28,14 @@ License
 template<class Type>
 void Foam::glTF::object::addData(const Type& fld)
 {
-    const label nComponents =
-        pTraits<typename Type::value_type>::nComponents;
+    const direction nCmpts = pTraits<typename Type::value_type>::nComponents;
 
     label count = data_.size();
-    data_.setSize(data_.size() + fld.size()*nComponents);
+    data_.resize(data_.size() + fld.size()*nCmpts);
 
     forAll(fld, fieldi)
     {
-        for (direction d = 0; d < nComponents; ++d)
+        for (direction d = 0; d < nCmpts; ++d)
         {
             data_[count++] = component(fld[fieldi], d);
         }
@@ -45,7 +44,7 @@ void Foam::glTF::object::addData(const Type& fld)
 
 
 template<class Type1, class Type2>
-void Foam::glTF::object::addData(const Type1& fld1, const Type2&fld2)
+void Foam::glTF::object::addData(const Type1& fld1, const Type2& fld2)
 {
     if (fld1.size() != fld2.size())
     {
@@ -55,26 +54,20 @@ void Foam::glTF::object::addData(const Type1& fld1, const Type2&fld2)
             << abort(FatalError);
     }
 
-    const label nComponents1 =
-        pTraits<typename Type1::value_type>::nComponents;
-
-    const label nComponents2 =
-        pTraits<typename Type2::value_type>::nComponents;
+    const direction nCmpts1 = pTraits<typename Type1::value_type>::nComponents;
+    const direction nCmpts2 = pTraits<typename Type2::value_type>::nComponents;
 
     label count = data_.size();
-    data_.setSize
-    (
-        data_.size() + fld1.size()*(nComponents1 + nComponents2)
-    );
+    data_.resize(data_.size() + fld1.size()*(nCmpts1 + nCmpts2));
 
     forAll(fld1, fieldi)
     {
-        for (direction d = 0; d < nComponents1; ++d)
+        for (direction d = 0; d < nCmpts1; ++d)
         {
             data_[count++] = component(fld1[fieldi], d);
         }
 
-        for (direction d = 0; d < nComponents2; ++d)
+        for (direction d = 0; d < nCmpts2; ++d)
         {
             data_[count++] = component(fld2[fieldi], d);
         }

src/fileFormats/gltf/foamGltfScene.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2021 OpenCFD Ltd.
+    Copyright (C) 2021-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -26,7 +26,8 @@ License
 \*---------------------------------------------------------------------------*/
 
 #include "foamGltfScene.H"
-#include "fileName.H"
+#include "OFstream.H"
+#include "OSspecific.H"
 
 // * * * * * * * * * * * * * * * * Constructors  * * * * * * * * * * * * * * //
 
@@ -43,6 +44,26 @@ Foam::glTF::scene::scene()
 
 // * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
 
+Foam::glTF::mesh& Foam::glTF::scene::getMesh(label meshi)
+{
+    const label lastMeshi = (meshes_.size() - 1);
+
+    if (meshi < 0)
+    {
+        meshi = (lastMeshi < 0 ? static_cast<label>(0) : lastMeshi);
+    }
+
+    if (meshi > lastMeshi)
+    {
+        FatalErrorInFunction
+            << "Mesh " << meshi << " out of range: " << lastMeshi
+            << abort(FatalError);
+    }
+
+    return meshes_[meshi];
+}
+
+
 Foam::label Foam::glTF::scene::addColourToMesh
 (
     const vectorField& fld,
@@ -51,13 +72,7 @@ Foam::label Foam::glTF::scene::addColourToMesh
     const scalarField& alpha
 )
 {
-    if (meshi > meshes_.size() - 1)
-    {
-        FatalErrorInFunction
-            << "Mesh " << meshi << " out of range "
-            << (meshes_.size() - 1)
-            << abort(FatalError);
-    }
+    auto& gmesh = getMesh(meshi);
 
     auto& bv = bufferViews_.create(name);
     bv.byteOffset() = bytes_;
@@ -71,21 +86,29 @@ Foam::label Foam::glTF::scene::addColourToMesh
 
     auto& obj = objects_.create(name);
 
-    if (alpha.size())
+    if (alpha.empty())
+    {
+        obj.addData(fld);
+    }
+    else
     {
         bv.byteLength() += fld.size()*sizeof(float);
         bytes_ += fld.size()*sizeof(float);
 
         acc.type() = "VEC4";
 
-        obj.addData(fld, alpha);
-    }
-    else
-    {
-        obj.addData(fld);
+        // Support uniform alpha vs full alpha field
+        tmp<scalarField> talpha(alpha);
+
+        if (alpha.size() == 1 && alpha.size() < fld.size())
+        {
+            talpha = tmp<scalarField>::New(fld.size(), alpha[0]);
+        }
+
+        obj.addData(fld, talpha());
     }
 
-    meshes_[meshi].addColour(acc.id());
+    gmesh.addColour(acc.id());
 
     return acc.id();
 }
@@ -136,13 +159,27 @@ void Foam::glTF::scene::addToAnimation
 }
 
 
+void Foam::glTF::scene::write(const fileName& outputFile)
+{
+    fileName jsonFile(outputFile.lessExt());
+    jsonFile.ext("gltf");
+
+    // Note: called on master only
+
+    if (!isDir(jsonFile.path()))
+    {
+        mkDir(jsonFile.path());
+    }
+
+    OFstream os(jsonFile);
+    write(os);
+}
+
+
 void Foam::glTF::scene::write(Ostream& os)
 {
-    const fileName base(os.name().lessExt());
-    const fileName binFile
-    (
-        fileName::concat(base.path(), fileName::name(base) + ".bin")
-    );
+    fileName binFile(os.name().lessExt());
+    binFile.ext("bin");
 
     // Write binary file
     // Note: using stdStream

src/fileFormats/gltf/foamGltfScene.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2021 OpenCFD Ltd.
+    Copyright (C) 2021-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -38,9 +38,10 @@ SourceFiles
 
 \*---------------------------------------------------------------------------*/
 
-#ifndef foam_gltf_scene_H
-#define foam_gltf_scene_H
+#ifndef Foam_gltf_scene_H
+#define Foam_gltf_scene_H
 
+#include "fileName.H"
 #include "foamGltfList.H"
 #include "foamGltfObject.H"
 #include "foamGltfMesh.H"
@@ -49,12 +50,15 @@ SourceFiles
 #include "foamGltfAnimation.H"
 #include "scalarField.H"
 #include "vectorField.H"
-#include "OFstream.H"
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 namespace Foam
 {
+
+// Forward Declarations
+class OFstream;
+
 namespace glTF
 {
 
@@ -85,6 +89,13 @@ class scene
         label bytes_;
 
 
+    // Private Member Functions
+
+        //- Non-const access to mesh at index (can be -1 for last mesh)
+        //  FatalError for out-of-bounds
+        mesh& getMesh(label meshi);
+
+
 public:
 
     // Constructors
@@ -114,16 +125,19 @@ public:
         (
             const Type& fld,
             const word& name,
-            const label meshi
+            const label meshId
         );
 
-        //- Returns accessor index
+        //- Add a colour field to the mesh, optionally with an alpha channel.
+        //  A constant alpha value can be specified as a field of size 1.
+        //
+        //  \returns accessor index
         label addColourToMesh
         (
-            const vectorField& fld,
+            const vectorField& fld,             //!< RGB colour field
             const word& name,
-            const label meshi,
-            const scalarField& alpha = scalarField()
+            const label meshId,
+            const scalarField& alpha = scalarField::null()  //!< Alpha channel
         );
 
         //- Returns index of last animation
@@ -139,7 +153,13 @@ public:
             const string& interpolation = "LINEAR"
         );
 
-        //- Write to stream (JSON and binary data)
+
+    // Write
+
+        //- Write to file pair (.gltf, .bin)
+        void write(const fileName& outputFile);
+
+        //- Write JSON (.gltf) to stream with auxiliary binary data (.bin)
         void write(Ostream& os);
 };
 

src/fileFormats/gltf/foamGltfSceneTemplates.C

@@ -33,11 +33,11 @@ Foam::label Foam::glTF::scene::addField
     const label target
 )
 {
-    const label nComponents = pTraits<typename Type::value_type>::nComponents;
+    const direction nCmpts = pTraits<typename Type::value_type>::nComponents;
 
     auto& bv = bufferViews_.create(name);
     bv.byteOffset() = bytes_;
-    bv.byteLength() = fld.size()*nComponents*sizeof(float);
+    bv.byteLength() = fld.size()*nCmpts*sizeof(float);
     if (target != -1)
     {
         bv.target() = target;
@@ -61,8 +61,8 @@ Foam::label Foam::glTF::scene::addMesh(const Type& fld, const word& name)
     const label accessorId =
         addField(fld, name, key(targetTypes::ARRAY_BUFFER));
 
-    auto& mesh = meshes_.create(name);
-    mesh.accessorId() = accessorId;
+    auto& gmesh = meshes_.create(name);
+    gmesh.accessorId() = accessorId;
 
     return meshes_.size() - 1;
 }
@@ -76,17 +76,11 @@ Foam::label Foam::glTF::scene::addFieldToMesh
     const label meshi
 )
 {
-    if (meshi > meshes_.size() - 1)
-    {
-        FatalErrorInFunction
-            << "Mesh " << meshi << " out of range "
-            << (meshes_.size() - 1)
-            << abort(FatalError);
-    }
+    auto& gmesh = getMesh(meshi);
 
     const label accessorId = addField(fld, name);
 
-    meshes_[meshi].addField(name, accessorId);
+    gmesh.addField(name, accessorId);
 
     return accessorId;
 }

src/fileFormats/gltf/foamGltfSceneWriter.C

@@ -0,0 +1,106 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | www.openfoam.com
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+    Copyright (C) 2022 OpenCFD Ltd.
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+\*---------------------------------------------------------------------------*/
+
+#include "foamGltfSceneWriter.H"
+#include "OFstream.H"
+#include "OSspecific.H"
+
+// * * * * * * * * * * * * * * * * Constructors  * * * * * * * * * * * * * * //
+
+Foam::glTF::sceneWriter::sceneWriter(const fileName& outputFile)
+:
+    ofile_(nullptr),
+    scene_(nullptr)
+{
+    open(outputFile);
+}
+
+
+// * * * * * * * * * * * * * * * * Destructor  * * * * * * * * * * * * * * * //
+
+Foam::glTF::sceneWriter::~sceneWriter()
+{
+    close();
+}
+
+
+// * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
+
+bool Foam::glTF::sceneWriter::valid() const noexcept
+{
+    return (ofile_ && scene_);
+}
+
+
+const Foam::fileName& Foam::glTF::sceneWriter::path() const
+{
+    return (ofile_ ? ofile_->name() : fileName::null);
+}
+
+
+const Foam::glTF::scene& Foam::glTF::sceneWriter::getScene() const
+{
+    return *scene_;
+}
+
+
+Foam::glTF::scene& Foam::glTF::sceneWriter::getScene()
+{
+    return *scene_;
+}
+
+
+void Foam::glTF::sceneWriter::open(const fileName& outputFile)
+{
+    close();
+
+    fileName jsonFile(outputFile.lessExt());
+    jsonFile.ext("gltf");
+
+    // Note: called on master only
+    if (!isDir(jsonFile.path()))
+    {
+        mkDir(jsonFile.path());
+    }
+
+    ofile_.reset(new OFstream(jsonFile));
+    scene_.reset(new glTF::scene());
+}
+
+
+void Foam::glTF::sceneWriter::close()
+{
+    if (ofile_ && scene_)
+    {
+        scene_->write(*ofile_);
+    }
+    ofile_.reset(nullptr);
+    scene_.reset(nullptr);
+}
+
+
+// ************************************************************************* //

src/fileFormats/gltf/foamGltfSceneWriter.H

@@ -0,0 +1,126 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | www.openfoam.com
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+    Copyright (C) 2022 OpenCFD Ltd.
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+Class
+    Foam::glTF::sceneWriter
+
+Description
+    Wrapper for glTF scene for file output
+
+SourceFiles
+    foamGltfSceneWriter.C
+
+\*---------------------------------------------------------------------------*/
+
+#ifndef Foam_gltf_sceneWriter_H
+#define Foam_gltf_sceneWriter_H
+
+#include "autoPtr.H"
+#include "fileName.H"
+#include "foamGltfScene.H"
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+namespace Foam
+{
+
+// Forward Declarations
+class OFstream;
+
+namespace glTF
+{
+
+/*---------------------------------------------------------------------------*\
+                     Class glTF::sceneWriter Declaration
+\*---------------------------------------------------------------------------*/
+
+class sceneWriter
+{
+    // Private Data
+
+        //- The backend output stream (json)
+        autoPtr<OFstream> ofile_;
+
+        //- The scene to output
+        autoPtr<glTF::scene> scene_;
+
+
+public:
+
+    // Generated Methods
+
+        //- No copy construct
+        sceneWriter(const sceneWriter&) = delete;
+
+        //- No copy assignment
+        void operator=(const sceneWriter&) = delete;
+
+
+    // Constructors
+
+        //- Default construct
+        sceneWriter() = default;
+
+        //- Construct and open with given file name
+        explicit sceneWriter(const fileName& outputFile);
+
+
+    //- Destructor - calls close()
+    ~sceneWriter();
+
+
+    // Member Functions
+
+        //- True if output file and scene exist
+        bool valid() const noexcept;
+
+        //- The json file name. Empty with !valid()
+        const fileName& path() const;
+
+        //- Const access to the scene. Error if valid() is not true!
+        const scene& getScene() const;
+
+        //- Non-const access to the scene. Error if valid() is not true!
+        scene& getScene();
+
+
+        //- Flush, output and open a new file for output
+        void open(const fileName& outputFile);
+
+        //- Write scene and close file
+        void close();
+};
+
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+} // End namespace glTF
+} // End namespace Foam
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+#endif
+
+// ************************************************************************* //