Use Online 3D Viewer for CAD files preview

[ReCoool]

Feature Description

This feature supports 3D preview for all of these file formats:
'3dm', '3ds', '3mf', 'amf', 'bim', 'brep', 'dae', 'fbx', 'fcstd', 'glb', 'gltf', 'ifc', 'igs', 'iges', 'stp', 'step', 'stl', 'obj', 'off', 'ply', 'wrl'

Intro

Hello everyone, I recently tried to implement the STL preview as it is described in docs.
The first problem i discovered was missing JQuery that needed to be loaded.
But then I wanted to add preview for other files and so I dug deeper.
I discovered an issue #5979 and this wonderful proposal from sapk to use Online 3D Viewer.
And so, I got to work.

My proposal

I think it would be great to implement this feature in docs as it is more versatile.
I tested it on PC and Android with all the supported files (the only one that didnt work was ".glb (v1)", v2 works fine).

The final implementation

Add template

In $GITEA_CUSTOM we need to add our template. This template should be saved in "$GITEA_CUSTOM/templates/custom/". Here create file "footer.tmpl" and add following text into it:

<!-- Load jQuery -->
<script src="/assets/scripts/jquery-3.6.0.min.js"></script>

<script>
  $(document).ready(function () {
    // Select links that end with any of the 3D file types
    const fileTypes = ['3dm', '3ds', '3mf', 'amf', 'bim', 'brep', 'dae', 'fbx', 'fcstd', 'glb', 'gltf', 'ifc', 'igs', 'iges', 'stp', 'step', 'stl', 'obj', 'off', 'ply', 'wrl'];
    const $3dLink = $('a.ui.mini.basic.button').filter(function () {
        const href = this.href.toLowerCase();
        return href.includes('/raw/') && fileTypes.some(ext => href.endsWith(`.${ext}`));
    });

    if ($3dLink.length) {
        var script = document.createElement('script');
        script.onload = function () {
            const fileUrl = $3dLink.attr("href");

            // Prepare the container for the viewer
            $(".file-view")
                .attr("id", "view-3d")
                .css({ padding: 0, margin: 0, height: "400px", width: "100%"})
                .empty();

            // get the parent element of the viewer
            let parentDiv = document.getElementById ('view-3d');

            // initialize the viewer with the parent element and some parameters
            let viewer = new OV.EmbeddedViewer (parentDiv, {
                backgroundColor : new OV.RGBAColor (59, 68, 76, 0),         // Transparent
                defaultColor : new OV.RGBColor (200, 200, 200),
                edgeSettings : new OV.EdgeSettings (false, new OV.RGBColor (0, 0, 0), 1),
                environmentSettings : new OV.EnvironmentSettings (
                    [
                        '/assets/o3dv/envmaps/fishermans_bastion/negx.jpg',
                        '/assets/o3dv/envmaps/fishermans_bastion/posx.jpg',
                        '/assets/o3dv/envmaps/fishermans_bastion/posy.jpg',
                        '/assets/o3dv/envmaps/fishermans_bastion/negy.jpg',
                        '/assets/o3dv/envmaps/fishermans_bastion/posz.jpg',
                        '/assets/o3dv/envmaps/fishermans_bastion/negz.jpg'
                    ],
                    false
                )
            });

            // load a model providing model urls
            viewer.LoadModelFromUrlList ([fileUrl]);
        };
        script.src = "/assets/o3dv/o3dv.min.js";

        document.head.appendChild(script);
    }
});  

console.log($("#view-3d").width(), $("#view-3d").height());
console.log(!!window.WebGLRenderingContext && !!document.createElement('canvas').getContext('webgl'));

</script>

Add public files

First, we need to add our JQuery script. This script will be saved in "$GITEA_CUSTOM/public/assets/scripts/". Here use e.g. wget to download the file.

wget https://code.jquery.com/jquery-3.6.0.min.js

Now we need to download latest version of O3DV. Go to "$GITEA_CUSTOM/public/assets/".
Create folder using (and cd into it):

mkdir o3dv
cd o3dv

Copy latest release zip link from GitHub (v0.15.0 as of now).
We can again use wget to download the file:

wget https://github.com/kovacsv/Online3DViewer/releases/download/0.15.0/o3dv.zip

Use e.g. unzip to unzip the archive:

unzip o3dv.zip

Folder permissions

Now the last thing. Change permissions on the "footer.tmpl":

chown git:git $GITEA_CUSTOM/templates/custom/footer.tmpl
chmod 770 $GITEA_CUSTOM/templates/custom/footer.tmpl

And on the public folder:

chown -R git:git $GITEA_CUSTOM/public

Now we have everything ready! Restart you gitea instance to apply these changes and you can test it in your browser.

The final words

If I missed something or you would like to know more, please leave a comment. I would be very glad if this would get changed in docs or even implemented natively.

Gitea info

As of now, I am running on v1.23.4.

Screenshots

No response

[KN4CK3R]

Now create a documentation pull request with your text. 👍

[lunny]

Thank you for your proposal. The jquery will be removed in the future version of Gitea. I think we should not include jquery here.

[ReCoool]

Hey, thanks for feedback!

Now create a documentation pull request with your text. 👍

I´ve not seen the docs source, so this might take me a while.

Thank you for your proposal. The jquery will be removed in the future version of Gitea. I think we should not include jquery here.

I converted the script to JS and tested it on both PC and Android (works like a charm) :D

<script>
    document.addEventListener('DOMContentLoaded', () => {
      // Supported 3D file types
      const fileTypes = ['3dm', '3ds', '3mf', 'amf', 'bim', 'brep', 'dae', 'fbx', 'fcstd', 'glb', 'gltf', 'ifc', 'igs', 'iges', 'step', 'stl', 'obj', 'off', 'ply', 'wrl'];
  
      // Select matching link
      const links = Array.from(document.querySelectorAll('a.ui.mini.basic.button'));
      const link3D = links.find(link => {
        const href = link.href.toLowerCase();
        return href.includes('/raw/') && fileTypes.some(ext => href.endsWith(`.${ext}`));
      });
  
      if (link3D) {
        const script = document.createElement('script');
        script.onload = () => {
          const fileUrl = link3D.getAttribute('href');
  
          // Prepare the container for the viewer
          const fileView = document.querySelector('.file-view');
          if (fileView) {
            fileView.setAttribute('id', 'view-3d');
            fileView.style.padding = '0';
            fileView.style.margin = '0';
            fileView.style.height = '400px';
            fileView.style.width = '100%';
            fileView.innerHTML = '';
          }
  
          // Initialize viewer
          const parentDiv = document.getElementById('view-3d');
          if (parentDiv) {
            const viewer = new OV.EmbeddedViewer(parentDiv, {
              backgroundColor: new OV.RGBAColor(59, 68, 76, 0), // Transparent
              defaultColor: new OV.RGBColor(200, 200, 200),
              edgeSettings: new OV.EdgeSettings(false, new OV.RGBColor(0, 0, 0), 1),
              environmentSettings: new OV.EnvironmentSettings([
                '/assets/o3dv/envmaps/fishermans_bastion/negx.jpg',
                '/assets/o3dv/envmaps/fishermans_bastion/posx.jpg',
                '/assets/o3dv/envmaps/fishermans_bastion/posy.jpg',
                '/assets/o3dv/envmaps/fishermans_bastion/negy.jpg',
                '/assets/o3dv/envmaps/fishermans_bastion/posz.jpg',
                '/assets/o3dv/envmaps/fishermans_bastion/negz.jpg'
              ], false)
            });
  
            // Load the model
            viewer.LoadModelFromUrlList([fileUrl]);
          }
        };
  
        script.src = '/assets/o3dv/o3dv.min.js';
        document.head.appendChild(script);
      }
    });
</script>

[ReCoool]

Ok, I added a pull request to the docs.

[lunny]

ref: https://gitea.com/gitea/docs/pulls/199