diff --git a/.gitignore b/.gitignore index 804a0ab..59a5874 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,6 @@ __pycache__/ .DS_Store -.vs_code/ +.vscode/ *.zip # the following ignores are used to ignore the local softlink files @@ -8,4 +8,6 @@ __pycache__/ rich meshio future -fileseq \ No newline at end of file +fileseq + +docs/_build/* \ No newline at end of file diff --git a/README.md b/README.md index 0837e83..810d88b 100644 --- a/README.md +++ b/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 diff --git a/__init__.py b/__init__.py index af4ada6..2f08102 100644 --- a/__init__.py +++ b/__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, 3), "blender": (3, 1, 0), "warning": "", "support": "COMMUNITY", diff --git a/bseq/importer.py b/bseq/importer.py index 4c896d0..640971b 100644 --- a/bseq/importer.py +++ b/bseq/importer.py @@ -183,7 +183,11 @@ def update_obj(scene, depsgraph=None): if obj.mode != "OBJECT": continue - current_frame = obj.BSEQ.frame + if depsgraph is not None: + current_frame = obj.evaluated_get(depsgraph).BSEQ.frame + else: + show_message_box("Warning: Might not be able load the correct frame because the dependency graph is not available.", "BSEQ Warning") + current_frame = obj.BSEQ.frame meshio_mesh = None pattern = obj.BSEQ.pattern if obj.BSEQ.use_relative: diff --git a/bseq/messenger.py b/bseq/messenger.py index d2956f5..507bc49 100644 --- a/bseq/messenger.py +++ b/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: diff --git a/bseq/panels.py b/bseq/panels.py index 7467fe7..4ef50e5 100644 --- a/bseq/panels.py +++ b/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") diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/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) diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000..a091b68 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/build.md b/docs/build.md new file mode 100644 index 0000000..269e963 --- /dev/null +++ b/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). diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..e11683c --- /dev/null +++ b/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.3' + +# -- 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 diff --git a/docs/format.md b/docs/format.md new file mode 100644 index 0000000..d822b68 --- /dev/null +++ b/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]() (`.ply`), +> [STL]() (`.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/Wiki/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. diff --git a/docs/frame.rst b/docs/frame.rst new file mode 100644 index 0000000..05753f4 --- /dev/null +++ b/docs/frame.rst @@ -0,0 +1,20 @@ +Frame control +============= + +You can use Blenders `driver system `_ 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 `_. + +.. 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 `_ for more details about how to edit the driver. + +.. image:: ../images/edit_driver.png + :align: center diff --git a/docs/global.md b/docs/global.md new file mode 100644 index 0000000..b21dfc2 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..c3ca94a --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,35 @@ +.. blender-sequence-loader documentation master file, created by + sphinx-quickstart on Sun Oct 2 13:42:11 2022. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to blender-sequence-loader's documentation! +=================================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + about + build + usage + global + + list + settings + +.. toctree:: + :maxdepth: 2 + :caption: Advanced: + + format + frame + script + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/docs/list.md b/docs/list.md new file mode 100644 index 0000000..73a8d50 --- /dev/null +++ b/docs/list.md @@ -0,0 +1,35 @@ +# List View + +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](https://docs.blender.org/manual/en/latest/interface/window_system/topbar.html?#render-menu)[^1]. This will prevent artifacts from occurring, especially if the user continues to operate the Blender interface during the render process. This is doubly relevant when using custom normals on meshes, as this might cause Blender to crash instead of just failing to load the correct geometry. + +![lock](../images/lock.png) + +[^1]: We have also had users stating that they are able to render perfectly well without enabling this setting, so you might be fine to disable this option if you need to. + +## Imported Sequence + +Here you can have an overview of all the sequences imported by this addon. When selecting a sequence, it will change the selected [active object](https://docs.blender.org/manual/en/latest/scene_layout/object/selecting.html#selections-and-the-active-object) as well. Vice versa, when the [active object](https://docs.blender.org/manual/en/latest/scene_layout/object/selecting.html#selections-and-the-active-object) changes, it will change the selection in this list view as well. + +![list](../images/list.png) + +## Enable & Disable + +It is possible to individually enable and disable sequences from updating when the animation frame changes. This is very useful when working with very large files or many sequences as it reduces the computational overhead of loading these sequences. Enabled means, that the sequence will be updated on frame change, and Disabled means that the sequence won't be updated on frame change. + +To toggle an individual sequence, you can click on the `ENABLED` or `DISABLED` button in the list view. + +![enable](../images/enable.png) + +### Enable Selected & Disable Selected + +When you want to enable or disable multiple sequences, you can [select](https://docs.blender.org/manual/en/latest/scene_layout/object/selecting.html) multiple objects in the viewport, and then click `Enable Selected` or `Disable Selected` to enable/disable all selected objects. + +## Current Frame + +`Current Frame` shows the current frame of sequence being loaded. By default, the value is [blender current frame](https://docs.blender.org/manual/en/latest/editors/timeline.html#frame-controls). For advanced usage, you can refer [here](./frame.md). + +## Refresh + +`Refresh Sequence` can be useful when the sequence is imported while the data is still being generated and not yet complete. Refreshing the sequence can detect the frames added after being imported. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..e149940 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +Sphinx==5.2.3 +sphinx_rtd_theme==1.0.0 +myst-parser==0.18.1 \ No newline at end of file diff --git a/docs/script.md b/docs/script.md new file mode 100644 index 0000000..2d66f0d --- /dev/null +++ b/docs/script.md @@ -0,0 +1,89 @@ +# Custom Script + +If you want to have your own way to import the mesh object, then you can write your own python script to read and import the mesh object. **Technically, you can write any python code here, so be careful of the risks, especially when executing unknown code.** + +A script is assigned on a **per object** basis, so you can have a different script for each object. + +## How to Enable it + +By default, this feature is turned off. You can enable it here by toggling the `Show Settings` in `Advanced` panel, then you can select the script you want to assign to this object. + +![script](../images/script.png) + +## Template + +We provide a simple template to show you how to use custom scripts. You can find the template as shown in the image. + +![template](../images/template.png) + +### template.py + +This one is the same as the default behavior of the addon. + +### dim3.py + +This template provides a way to import 3D volumetric meshes, particularly tetrahedra and hexahedron. + +The default behavior of the addon is that faces inside 3D meshes are discarded, since they are invisible in most cases. But sometimes, these inner faces can be useful, and you can use this addon to import these inner faces in a specific way. + +## Write Your Own Script + +If you want to write your own script, you only need to implement one of two methods. One is `preprocess`, another one is `process`. + +### Notes: + +There are many things to be careful with here: + +1. `process` has higher priority than `preprocess`, when `process` exist, `preprocess` will be ignored. +2. When neither of these two functions exist, the addon will use the default behavior. +3. If you write any other things, it will be ignored, such as import modules, e.g. `import numpy`, or write a helper function which you call inside of `process` or `preprocess`. +4. If you need to import modules, write it inside the `preprocess` or `process` function. For example + +```python +def preprocess(fileseq: fileseq.FileSequence, frame_number: int) -> meshio.Mesh: + import math + # math.sqrt(25) +``` + +5. These modules are available by default: `numpy`, `meshio`, `fileseq` +6. There is also a very useful convenience function available: + + +```python +def update_mesh(meshio_mesh: meshio.Mesh, mesh: bpy.types.Mesh): + # this function reads `meshio_mesh`, then write it into `mesh`, and old information of `mesh` will be lost. +``` + +### preprocess + +The function `preprocess` has the following signature + +```python +def preprocess(fileseq: fileseq.FileSequence, frame_number: int) -> meshio.Mesh: + pass +``` + +This function, takes 2 parameters +1. fileseq: the `filseq` object when imported +2. frame_number: blender current frame + +This function expects a return value of `meshio.Mesh` object, and then the addon will write this `meshio.Mesh` into Blender. For details about `meshio.Mesh` object, can be found [here](https://github.com/nschloe/meshio/wiki/meshio-Mesh()-data-structure). + +### process + +The function `preprocess` has the following signature + +```python +def process(fileseq: fileseq.FileSequence, frame_number: int, mesh: bpy.types.Mesh): + pass +``` + +This function, takes 3 parameters + +1. fileseq: the `filseq` object when imported +2. frame_number: blender current frame +3. mesh: [bpy.types.Mesh](https://docs.blender.org/api/current/bpy.types.Mesh.html#bpy.types.Mesh) object + +This function will directly read the file, then modify the `mesh` object, rather than constructing a `meshio.Mesh` object in between. It can be useful if `meshio.Mesh` is not versatile enough to hold the mesh information you want. + +But in general, it's much more complicated to construct the `bpy.types.Mesh` object, so we suggest that you use `preprocess` for the most cases, unless you really need `process` function. diff --git a/docs/settings.md b/docs/settings.md new file mode 100644 index 0000000..a706fea --- /dev/null +++ b/docs/settings.md @@ -0,0 +1,50 @@ +# Settings + +Here you can find settings for each sequence. + +## Sequence Information (read-only) + +This is **read-only** information to show the pattern of this sequence, and if it's using a relative path. + +![sequence_information](../images/sequence_information.png) + +## Geometry Nodes + +While all files are imported as plain geometry, we provide some templates that we have found to be incredibly useful for visualizing particle data. The exact [geometry node](https://docs.blender.org/manual/en/latest/modeling/geometry_nodes/index.html) setup can be seen in the [geometry nodes tab](https://docs.blender.org/manual/en/latest/editors/geometry_node.html) and may be modified as desired, e.g. to set the particle radius. + +When applying the `Point Cloud` geometry node, the vertices of the mesh are converted to a [Point Cloud](https://docs.blender.org/manual/en/latest/modeling/point_cloud.html), which can be rendered only by [Cycles](https://docs.blender.org/manual/en/latest/render/cycles/introduction.html) and only as spheres. + +When applying the `Instances` geometry node, the vertices of the mesh are converted to cubes, which can be rendered by both [Eevee](https://docs.blender.org/manual/en/latest/render/eevee/index.html) and [Cycles](https://docs.blender.org/manual/en/latest/render/cycles/introduction.html). You are free to change instanced object in [Geometry Node Editor](https://docs.blender.org/manual/en/latest/editors/geometry_node.html). + +**CAUTION: Because this node setup relies on the [`Realize Instances`](https://docs.blender.org/manual/en/latest/modeling/geometry_nodes/instances/realize_instances.html) node, the memory usage increases extremely rapidly. Make sure to save the `.blend` file before attempting this, as Blender may run out of memory!!! Depending on your hardware and instanced object, it may be safe to use as many as 100k particles.** + +Applying the `Mesh` geometry node will restore the default geometry nodes, which simply displays the imported geometry as it is. + +![geometry_nodes](../images/geometry_nodes.png) + +Notes: + +1. `Instances` is super memory hungry compared to `Point Cloud`. +2. After applying `Point Cloud` or `Instances` geometry nodes, you need to assign the material inside the geometry nodes, to be able to shade the object according to some imported field. 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`](https://docs.blender.org/manual/en/latest/render/shader_nodes/input/attribute.html) node in the [Shader Editor](https://docs.blender.org/manual/en/latest/editors/shader_editor.html) and simply specify the attribute string. The imported attributes can be seen in the [spreadsheet](https://docs.blender.org/manual/en/latest/editors/spreadsheet.html) browser of the Geometry Nodes tab and are also listed in the [addon UI](#attributes). + + +## Attributes + +This addon will also import attributes[^1] of the mesh object into the blender [attribute](https://docs.blender.org/manual/en/latest/modeling/geometry_nodes/attributes_reference.html) system. + +Here it shows all the vertex attributes detected and imported. To avoid name collisions with [blender built-in attributes](https://docs.blender.org/manual/en/latest/modeling/geometry_nodes/attributes_reference.html#built-in-attributes), all names are renamed using `bseq_` as prefix. Names are read-only. For example, `id` -> `bseq_id`. Keep this in mind when accessing attributes in the shader editor. + +The value of the attributes can be viewed in blenders [spreadsheet](https://docs.blender.org/manual/en/latest/editors/spreadsheet.html) which is part of the geometry nodes tab. There are many ways to use these attributes, such as [attribute node](https://docs.blender.org/manual/en/latest/render/shader_nodes/input/attribute.html) when shading. + +![attribute](../images/attribute.png) + +[^1]: Vertex attributes only for now + +### Split Norm per Vertex + +We also provide the ability to use a per-vertex vector attribute as custom normals for shading. For more details check the official documentation [here](https://docs.blender.org/manual/en/latest/modeling/meshes/structure.html#modeling-meshes-normals-custom). + +The button `Set selected as normal` will set current selected attribute as vertex normal[^2]. The button `Clear normal` will reset the vertex normal to use the default face normals. + +[^2]: The addon does not check if the selected attribute is suitable for normals or not, e.g. if the data type of the attribute is an integer instead of float, then Blender will simply give a runtime error. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..663ce22 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,65 @@ +# Usage + +**DISCLAIMER**: Some of the screenshots may not be up to date with the most recent version of the addon, especially with respect to the text and ordering of UI elements. + +The following clip shows the basic usage of the addon. In particular, it shows how to load and render a sequence of particles data. + +For the supported file formats refer to [here](./format.md). + +![usage](../images/usage.gif) + +## Access + +After installing addon, you can find it in the toolbar, which is accessible by clicking on the small arrow at the top right of the viewport or by pressing the `n` key on the keyboard. + +![drag](../images/drag.png) + +Then you can find it here. + +![location](../images/location.png) + +## Basic Import Settings + +### Directory + +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 to navigate to the directory and click "Accept". Files are shown but not selectable in this dialogue.** + +![directory](../images/directory.png) + +### Absolute vs. Relative Paths + +There is a small checkbox asking whether you want to use relative paths or not. + +When toggled **on**, the blender file **must be saved before loading the sequence**. Then this sequence will be loaded using the relative path from the location of the saved `.blend` file. As such, if you move the `.blend` file in conjunction with the data to another directory (keeping their relative locations the same) the sequence loader will still work. This is especially useful when working with cloud synchronized folders, whose absolute paths may be different on different computers. + +If toggled **off (default)**, it will use the **absolute path to load the sequence**. For this, the `.blend` file does not have to be saved in advance. + +![path](../images/path.png) + +### File Sequences + +After selecting the directory, the addon will automatically detect all sequences in this directory, and automatically select the first one as the default value in `Sequence Pattern` box. If only one sequence exists, it will be used by default. When there are multiple patterns you can use the dropdown to select a different pattern. + +The sequences that can be detected usually have the format `{name}{frame_number}.{extension}`. For example, two files with names `Example0.obj`, `Example1.obj` can be detected as a sequence. For more details, you can check it in [fileseq](https://github.com/justinfx/fileseq) project. + +![sequence](../images/sequence.png) + +#### Custom Pattern + +Sometimes, the addon can't detect the sequences correctly, or there are too many sequences in this directory. Then you can manually type the sequence. + +First, enable the `Use Custom Pattern` button, then `Sequence Pattern` becomes to editable. + +![custom](../images/custom.png) + +The grammar for this sequence is to use a `@` or `#` as an indicator for a frame index. An example could be `example@.vtk`. For more details, you can check the [fileseq](https://github.com/justinfx/fileseq#check-a-directory-for-one-existing-sequence) project. + +## Edit Sequence + +Sometimes, if you want to keep the setup of the current blender file, such as name and materials, but you want to change the loaded files. You can do this by using `Edit Sequence Path`. + +First, you need to select the sequence you want to edit. You can select [**any of the objects imported by this addon**](./list.md). By default, the value is the [current active object](https://docs.blender.org/manual/en/latest/scene_layout/object/selecting.html#selections-and-the-active-object). If current object is not imported by this addon, such as a general cube, light, then it's the last active object imported by this addon. + +After clicking the `Edit Sequence Path`, the sequence information will be updated to the sequence provided in [Basic Import Settings](#basic-import-settings). + +![edit](../images/edit.png) diff --git a/images/1.png b/images/1.png deleted file mode 100644 index e70076c..0000000 Binary files a/images/1.png and /dev/null differ diff --git a/images/2.png b/images/2.png deleted file mode 100644 index d2a6eb7..0000000 Binary files a/images/2.png and /dev/null differ diff --git a/images/3.png b/images/3.png deleted file mode 100644 index 8f2aa45..0000000 Binary files a/images/3.png and /dev/null differ diff --git a/images/4.png b/images/4.png deleted file mode 100644 index 8834678..0000000 Binary files a/images/4.png and /dev/null differ diff --git a/images/5.png b/images/5.png deleted file mode 100644 index f98e1ef..0000000 Binary files a/images/5.png and /dev/null differ diff --git a/images/7.png b/images/7.png deleted file mode 100644 index 0127f8f..0000000 Binary files a/images/7.png and /dev/null differ diff --git a/images/attribute.png b/images/attribute.png new file mode 100644 index 0000000..dff7f0a Binary files /dev/null and b/images/attribute.png differ diff --git a/images/auto_refresh.png b/images/auto_refresh.png new file mode 100644 index 0000000..a40d102 Binary files /dev/null and b/images/auto_refresh.png differ diff --git a/images/current_frame.png b/images/current_frame.png new file mode 100644 index 0000000..b8bc398 Binary files /dev/null and b/images/current_frame.png differ diff --git a/images/custom.png b/images/custom.png new file mode 100644 index 0000000..fe20858 Binary files /dev/null and b/images/custom.png differ diff --git a/images/directory.png b/images/directory.png new file mode 100644 index 0000000..e601c47 Binary files /dev/null and b/images/directory.png differ diff --git a/images/0.png b/images/drag.png similarity index 100% rename from images/0.png rename to images/drag.png diff --git a/images/edit.png b/images/edit.png new file mode 100644 index 0000000..866fa35 Binary files /dev/null and b/images/edit.png differ diff --git a/images/edit_driver.png b/images/edit_driver.png new file mode 100644 index 0000000..1646bf2 Binary files /dev/null and b/images/edit_driver.png differ diff --git a/images/enable.png b/images/enable.png new file mode 100644 index 0000000..439273e Binary files /dev/null and b/images/enable.png differ diff --git a/images/geometry_nodes.png b/images/geometry_nodes.png new file mode 100644 index 0000000..c731d2f Binary files /dev/null and b/images/geometry_nodes.png differ diff --git a/images/list.png b/images/list.png new file mode 100644 index 0000000..09f119c Binary files /dev/null and b/images/list.png differ diff --git a/images/location.png b/images/location.png new file mode 100644 index 0000000..074a05a Binary files /dev/null and b/images/location.png differ diff --git a/images/6.png b/images/lock.png similarity index 100% rename from images/6.png rename to images/lock.png diff --git a/images/path.png b/images/path.png new file mode 100644 index 0000000..bd05287 Binary files /dev/null and b/images/path.png differ diff --git a/images/print.png b/images/print.png new file mode 100644 index 0000000..c1074ff Binary files /dev/null and b/images/print.png differ diff --git a/images/script.png b/images/script.png new file mode 100644 index 0000000..a167eec Binary files /dev/null and b/images/script.png differ diff --git a/images/sequence.png b/images/sequence.png new file mode 100644 index 0000000..a32bdcd Binary files /dev/null and b/images/sequence.png differ diff --git a/images/sequence_information.png b/images/sequence_information.png new file mode 100644 index 0000000..3a59a24 Binary files /dev/null and b/images/sequence_information.png differ diff --git a/images/template.png b/images/template.png new file mode 100644 index 0000000..639895f Binary files /dev/null and b/images/template.png differ diff --git a/images/usage.gif b/images/usage.gif new file mode 100644 index 0000000..19a19b9 Binary files /dev/null and b/images/usage.gif differ