add doc

Author: losanc

.gitignore

@@ -8,4 +8,6 @@ __pycache__/
 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
 

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,49 @@
+# Description
+
+This is an addon for Blender 3.1+ (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
+
+Here is a gif to show the basic usage of this addon. In this gif, it shows how to load and render a sequence of particles 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).
+
+
+## Dependencies
+
+|name | link | license| description|
+|---|---|---|---|
+|meshio | [link](https://github.com/nschloe/meshio) | MIT| import the mesh|
+|fileseq | [link](https://github.com/justinfx/fileseq) | MIT | detect and load 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,55 @@
+# 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 [release](https://github.com/InteractiveComputerGraphics/blender-sequence-loader/releases) page
+
+## Install the zip file
+
+You can check [here](https://docs.blender.org/manual/en/latest/editors/preferences/addons.html#installing-add-ons) for installing and enabling the addon.
+
+## 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,
+```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,31 @@
+# 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']
+
+
+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/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 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.md

@@ -0,0 +1,18 @@
+# Frame control
+
+
+You can use blender [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).
+
+![current frame](../images/current_frame.png)
+
+
+## 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.
+
+![edit frame](../images/edit_driver.png)
+

docs/global.md

@@ -0,0 +1,26 @@
+# Global Settings
+
+There are two global settings
+1. Print information: default on
+1. Auto Refresh: default off
+
+## Print information
+
+When this button toggled, it will print information about the sequence imported by this addon, such as name of the object into a file.
+
+The file has the name `bseq_{time}`, `{time}` is the time when rendering starts.
+
+The file will be in the same direction as [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 toggled, it will [refresh](./list.md#refresh) **all the sequence whenever frame changes**.
+
+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 added after being imported.
+
+![auto refresh](../images/auto_refresh.png)

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`

docs/list.md

@@ -0,0 +1,36 @@
+# 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.
+
+![lock](../images/lock.png)
+
+[^1]: Or maybe not, I am not 100% percent sure about this.
+
+## Imported Sequence
+
+Here you can have an overview of all the sequence imported by this addon. And you can select either one of them, it will change [active object](https://docs.blender.org/manual/en/latest/scene_layout/object/selecting.html#selections-and-the-active-object) to it as well. When [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 change 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, 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 find it [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.