Update (#6)

* restructure to support additional file formats

* update for dim3 template

* rename simloader to bseq

* minor fix

* add notes

* use blender driver system to control frames

* small update with frame driver

* disbale the function when not in object mode

* small fix

* rewrite edit

* add global settings for refresh

* small bug fix

* minor change

* add doc

* remove old images

* update version

* update doc

* fix doc

* language fixes

* remove warning, because the driver system was fixed after all

Co-authored-by: Stefan Jeske <[email protected]>

Author: losanc

.gitignore

@@ -1,11 +1,13 @@
 __pycache__/
 .DS_Store
-.vs_code/
+.vscode/
 *.zip
 
 # the following ignores are used to ignore the local softlink files
 # the extern folder won't be affected by this
 rich
 meshio
 future
-fileseq
+fileseq
+
+docs/_build/*

README.md

@@ -87,21 +87,21 @@ DISCLAIMER: Some of the screenshots may not be up to date with the most recent v
 
 After installing addon, you can find it in the toolbar, which is accessible here or toggled by pressing the `n` key.
 
-![start](images/0.png)
+![drag](images/drag.png)
 
 Then you can find it here.
 
-![homepage](images/1.png)
+![homepage](images/location.png)
 
 ### 2. Load the animation sequence you want
 
 You can select the directory in which your data is located through the GUI by clicking the rightmost icon. It will open the default blender file explorer. Then you can go to the directory you want, for example, like image showed below. **You only need navigate to the directory and click "Accept". Files are shown but not selectable in this dialogue.**
 
-![selecticon](images/2.png)
+![directory](images/directory.png)
 
 Then the addon will automatically try to detect the sequences in this directory, so that you simply select the sequence you want. If the desired sequence is not shown, you can switch to enter a manual pattern, where a single `@` character is used to denote a running frame index.
 
-![after_selecting](images/3.png)
+![sequence](images/sequence.png)
 
 #### 2.1 Absolute vs. Relative Paths
 
@@ -111,19 +111,19 @@ When toggled on, the blender file must be saved before loading the sequence. The
 
 If toggled off (default), it will use absolute path to load the sequence. For this, the `.blend` file does not have to be saved in advance.
 
-![relative_path](images/4.png)
+![relative_path](images/path.png)
 
 #### 2.2 Sequence List View
 
 After the sequence being imported, it will be available in the `Imported Sequences` panel, with more settings being available in `Sequence Settings` panel once a sequence has been selected.
 
-![settings](images/5.png)
+![settings](images/list.png)
 
 By default, all supported file formats are simply imported as geometry (a collection of vertices, lines, triangles and quads). As such, you should be able to directly play/render the animation if it contains geometry.
 
 Note: When rendering the animation, please turn on the `Lock Interface`. This will prevent artifacts from occurring, especially if the user continues to operate the Blender interface during the render process.
 
-![lock interface](images/6.png)
+![lock interface](images/lock.png)
 
 ##### 2.2.1 Enable/ Disable
 
@@ -152,7 +152,7 @@ Notes:
 2. After applying `Point Cloud` or `Instances` geometry nodes, you need to assign the material inside the geometry nodes. So to save your work, you can simply assign the material here, then apply the `Point Cloud` or `Instances` geometry nodes.
 3. To access the attributes for shading, use the `Attribute` node in the Shader Editor and simply specify the attribute string. The imported attributes can be seen in the spreadsheet browser of the Geometry Nodes tab and are also listed in the addon UI.
 
-![material](images/7.png)
+![material](images/geometry_nodes.png)
 
 #### 2.3.2 Path Information
 

__init__.py

@@ -2,7 +2,7 @@
     "name": "Sequence Loader",
     "description": "Loader for meshio supported mesh files/ simulation sequences",
     "author": "Interactive Computer Graphics",
-    "version": (0, 1, 1),
+    "version": (0, 1, 2),
     "blender": (3, 1, 0),
     "warning": "",
     "support": "COMMUNITY",

bseq/messenger.py

@@ -2,8 +2,11 @@
 
 
 def selected_callback():
-    if not bpy.context.view_layer.objects.active:
-        return
+
+    # seems like that this is not necessary
+    # if not bpy.context.view_layer.objects.active:
+    #     return
+
     name = bpy.context.active_object.name
     idx = bpy.data.objects.find(name)
     if idx >= 0:

bseq/panels.py

@@ -196,6 +196,15 @@ def draw(self, context):
         split = layout.split()
         col1 = split.column()
         col2 = split.column()
+
+        # check if edit_obj exist
+        # if not exist any more, then delete the object manually
+        # see here https://blender.stackexchange.com/a/164835 for more details
+        # I personally think this implementation is not a good design,
+        # but can't think of any better ways now
+        if importer_prop.edit_obj and context.scene.objects.get(importer_prop.edit_obj.name) == None:
+            bpy.data.objects.remove(importer_prop.edit_obj)
+
         col1.prop_search(importer_prop, 'edit_obj', bpy.data, 'objects', text="")
         col2.operator("sequence.edit")
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/about.md

@@ -0,0 +1,50 @@
+# Description
+
+This is an addon for Blender 3.1+ (it might work with 2.8+ but has not been tested) that enables loading of file sequences. The addon comes bundled together with [meshio](https://github.com/nschloe/meshio) which enables the loading of geometric data from a multitude of [file formats](./format.md).
+
+All data is loaded *just-in-time* when the Blender frame changes, in order to avoid excessive memory consumption. By default, the addon is able to load vertices, lines, triangles and quads. It is also able to automatically extract triangle and quad surface meshes from tetrahedral and hexahedral volume meshes. Scalar and vector attributes on vertices are also imported for visualization purposes.
+
+## Basic usage
+
+This video shows the basic usage of this addon, i.e. how to load and render a simple sequence of particle data
+
+![usage](../images/usage.gif)
+
+## Affected Blender Settings
+
+This addon will change the value of `Preferences`->`Save & Load` ->`Default To` ->`Relative Paths` to `false`. Default value is `true`. For information can be found [here](https://docs.blender.org/manual/en/latest/editors/preferences/save_load.html#blend-files).
+
+This addon will also modify the `sys.path` variable of Blender python environment, by inserting the path of the addon itself. This makes it possible to use the bundled libraries.
+
+## Dependencies
+
+| name          | link                                                    | license | description                 |
+| ------------- | ------------------------------------------------------- | ------- | --------------------------- |
+| meshio        | [link](https://github.com/nschloe/meshio)               | MIT     | Loading mesh data           |
+| fileseq       | [link](https://github.com/justinfx/fileseq)             | MIT     | Detection of file sequences |
+| rich          | [link](https://github.com/Textualize/rich)              | MIT     | dependency of meshio        |
+| python-future | [link](https://github.com/PythonCharmers/python-future) | MIT     | dependency of fileseq       |
+
+## License
+
+MIT License
+
+Copyright (c) 2022 Interactive Computer Graphics 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/build.md

@@ -0,0 +1,52 @@
+# Build and install the addon
+
+## Build from source
+
+1. Clone the project to download both project and dependencies
+
+```shell
+git clone https://github.com/InteractiveComputerGraphics/blender-sequence-loader.git  --recurse-submodules
+```
+
+2.  Build the installable .zip file by simply running the following command. This should produce a file called `blender_sequence_loader_{date}.zip`, where `{date}` is replaced with todays date. No other dependency other than standard python3 libraries are needed to build the addon.
+
+```python
+python3 build_addon.py
+```
+
+
+## Download from release page
+
+Or you can simply download the latest `.zip` file from the [releases](https://github.com/InteractiveComputerGraphics/blender-sequence-loader/releases) page.
+
+## Install the zip file
+
+You can check the official Blender documentation [here](https://docs.blender.org/manual/en/latest/editors/preferences/addons.html#installing-add-ons) for installing and enabling addons.
+
+## For developers
+
+If you want to develop this addon, using soft link (on Linux/macOS) / [Symlinks](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/) (on Windows) can be very helpful.
+
+### *-nix Users
+
+Once you have cloned the project, go to the root directory of this addon, you can create symlink as follows
+```bash
+ln -s extern/meshio/src/meshio meshio
+ln -s extern/rich/rich/ rich
+ln -s extern/fileseq/src/fileseq fileseq
+ln -s extern/python-future/src/future/ future
+```
+
+Then create a soft link to link from the [blender addon directory](https://docs.blender.org/manual/en/latest/advanced/blender_directory_layout.html)[^1] to the directory where you download and unzip the files. For example this could look like this on MacOS,
+
+```bash
+ln -s ~/Downloads/blender-sequence-loader ~/Library/Application Support/Blender/3.1/scripts/addons/blender-sequence-loader-dev
+```
+
+[^1]: By default, `{USER}/scripts/addons`, `{USER}`: Location of configuration files (typically in the user’s home directory).
+
+### Windows Users
+
+You can use [mklink](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/mklink) to do the same things as *-nix users. [^2]
+
+[^2]: You will need either administrator permission, or [developer mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development).

docs/conf.py

@@ -0,0 +1,36 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'blender-sequence-loader'
+copyright = '2022, InteractiveComputerGraphics'
+author = 'InteractiveComputerGraphics'
+release = '0.1.2'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['myst_parser','sphinx_rtd_theme']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ['_static']
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'markdown',
+    '.md': 'markdown',
+}
+
+
+myst_heading_anchors = 2

docs/format.md

@@ -0,0 +1,54 @@
+# File Formats
+
+The current file formats supported by [meshio](https://github.com/nschloe/meshio)  [^1] are
+
+> [Abaqus](http://abaqus.software.polimi.it/v6.14/index.html) (`.inp`),
+> ANSYS msh (`.msh`),
+> [AVS-UCD](https://lanl.github.io/LaGriT/pages/docs/read_avs.html) (`.avs`),
+> [CGNS](https://cgns.github.io/) (`.cgns`),
+> [DOLFIN XML](https://manpages.ubuntu.com/manpages/jammy/en/man1/dolfin-convert.1.html) (`.xml`),
+> [Exodus](https://nschloe.github.io/meshio/exodus.pdf) (`.e`, `.exo`),
+> [FLAC3D](https://www.itascacg.com/software/flac3d) (`.f3grid`),
+> [H5M](https://www.mcs.anl.gov/~fathom/moab-docs/h5mmain.html) (`.h5m`),
+> [Kratos/MDPA](https://github.com/KratosMultiphysics/Kratos/wiki/Input-data) (`.mdpa`),
+> [Medit](https://people.sc.fsu.edu/~jburkardt/data/medit/medit.html) (`.mesh`, `.meshb`),
+> [MED/Salome](https://docs.salome-platform.org/latest/dev/MEDCoupling/developer/med-file.html) (`.med`),
+> [Nastran](https://help.autodesk.com/view/NSTRN/2019/ENU/?guid=GUID-42B54ACB-FBE3-47CA-B8FE-475E7AD91A00) (bulk data, `.bdf`, `.fem`, `.nas`),
+> [Netgen](https://github.com/ngsolve/netgen) (`.vol`, `.vol.gz`),
+> [Neuroglancer precomputed format](https://github.com/google/neuroglancer/tree/master/src/neuroglancer/datasource/precomputed#mesh-representation-of-segmented-object-surfaces),
+> [Gmsh](https://gmsh.info/doc/texinfo/gmsh.html#File-formats) (format versions 2.2, 4.0, and 4.1, `.msh`),
+> [OBJ](https://en.wikipedia.org/wiki/Wavefront_.obj_file) (`.obj`),
+> [OFF](https://segeval.cs.princeton.edu/public/off_format.html) (`.off`),
+> [PERMAS](https://www.intes.de) (`.post`, `.post.gz`, `.dato`, `.dato.gz`),
+> [PLY](<https://en.wikipedia.org/wiki/PLY_(file_format)>) (`.ply`),
+> [STL](<https://en.wikipedia.org/wiki/STL_(file_format)>) (`.stl`),
+> [Tecplot .dat](http://paulbourke.net/dataformats/tp/),
+> [TetGen .node/.ele](https://wias-berlin.de/software/tetgen/fformats.html),
+> [SVG](https://www.w3.org/TR/SVG/) (2D output only) (`.svg`),
+> [SU2](https://su2code.github.io/docs_v7/Mesh-File/) (`.su2`),
+> [UGRID](https://www.simcenter.msstate.edu/software/documentation/ug_io/3d_grid_file_type_ugrid.html) (`.ugrid`),
+> [VTK](https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf) (`.vtk`),
+> [VTU](https://vtk.org/Uncyclo/VTK_XML_Formats) (`.vtu`),
+> [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) ([TIN](https://en.wikipedia.org/wiki/Triangulated_irregular_network)) (`.wkt`),
+> [XDMF](https://xdmf.org/index.php/XDMF_Model_and_Format) (`.xdmf`, `.xmf`).
+
+The additionally supported file formats are
+
+> [bgeo](https://github.com/wdas/partio)(`.bgeo`) [^2]
+> [mzd](https://github.com/InteractiveComputerGraphics/MayaMeshTools/tree/main/extern/mzd)(`.mzd`)
+
+[^1]: Not all of the formats have been tested for this addon and some issues may still occur.
+
+[^2]: The addon only supports particle-only `.bgeo`  files
+
+## Add support for customized file formats
+
+You can add support for your own customized file formats. For example, if you want to support `.example` file formats.
+
+To do that,
+1. Create a `example.py` file in the folder additional_file_formats
+2. Implement a function `def readexample_to_meshio(filepath):`, which reads the file from `filepath`, then construct a [meshio.Mesh](https://github.com/nschloe/meshio/wiki/meshio-Mesh()-data-structure) object. 
+3. Add `meshio.register_format("example", [".example"], readexample_to_meshio, {".example": None})` in the global space
+4. Add `from . import example` in `additional_file_formats/__init__.py`
+
+You can check [additional_file_formats/bgeo.py](https://github.com/InteractiveComputerGraphics/blender-sequence-loader/blob/main/additional_file_formats/bgeo.py) as an example.

docs/frame.rst

@@ -0,0 +1,20 @@
+Frame control
+=============
+
+You can use Blenders `driver system <https://docs.blender.org/manual/en/latest/animation/drivers/index.html>`_ to control the frame of the sequence.
+
+Default settings
+*****************
+
+Each sequence has its own property ``Current Frame`` to control its frame. By default, the value equals to the `blender current frame <https://docs.blender.org/manual/en/latest/editors/timeline.html#frame-controls>`_.
+
+.. image:: ../images/current_frame.png
+	:align: center
+
+Change the value
+*****************
+
+Right click on the ``Current Frame`` property, then click ``Edit Driver``. You can check  `here <https://docs.blender.org/manual/en/latest/animation/drivers/drivers_panel.html>`_ for more details about how to edit the driver.
+
+.. image:: ../images/edit_driver.png
+	:align: center

docs/global.md

@@ -0,0 +1,26 @@
+# Global Settings
+
+There are two global settings
+
+1. Print information: default `true`
+1. Auto Refresh: default `false`
+
+## Print information
+
+When this button is toggled, it will print information about the sequence imported by this addon, such as name of the object, into a separate file.
+
+The file has the naming pattern `bseq_{time}`, where `{time}` is the time when rendering is started.
+
+The file will be located in the [blender render output directory](https://docs.blender.org/manual/en/latest/editors/preferences/file_paths.html#render). [^1]
+
+![print](../images/print.png)
+
+[^1]: By default the value is `/tmp`, and this directory does not exit on windows system. So when the directory does not exist, it won't print information into file.
+
+## Auto Refresh
+
+When this button is toggled, it will [refresh](./list.md#refresh) **all the sequences whenever a frame change occurs**.
+
+This option can be useful when some of the sequences are imported while the data is still being generated and not yet complete. Refreshing all the sequences can detect the frames that were added after being initially imported.
+
+![auto refresh](../images/auto_refresh.png)