Merge branch 'sjeske/ui-improvements' into 'master'

Prepare for public release

See merge request hhui/blendertool!3

Author: losanc

README.md

@@ -1,116 +1,135 @@
-# SimLoader
-Loading animation sequences with meshio and fileseq
-
+![](images/logo.svg)
 
-## 1. Clone the project
-`git clone https://www.graphics.rwth-aachen.de:9000/hhui/blendertool  --recurse-submodules` to download both project and dependencies
+Loading animation sequences with meshio and fileseq
 
+- [1. Installation](#1-installation)
+  - [1.1 Build from source (optional)](#11-build-from-source-optional)
+  - [1.2 Install Addon](#12-install-addon)
+  - [1.3 FAQs](#13-faqs)
+- [2. How to use](#2-how-to-use)
+  - [2. Load the animation sequence you want](#2-load-the-animation-sequence-you-want)
+    - [2.1 Absolute vs. Relative Paths](#21-absolute-vs-relative-paths)
+    - [2.2 Sequence List View](#22-sequence-list-view)
+      - [2.2.1 Enable/ Disable](#221-enable-disable)
+      - [2.2.1 Refresh Sequence](#221-refresh-sequence)
+    - [2.3 Settings](#23-settings)
+    - [2.3.1 Geometry Nodes](#231-geometry-nodes)
+    - [2.3.2 Path Information](#232-path-information)
+    - [2.3.3 Attributes Settings](#233-attributes-settings)
+    - [2.3.4 Split Norm per Vertex](#234-split-norm-per-vertex)
 
-## 2. Build & Install
+## 1. Installation
 
-1. Build manually
+### 1.1 Build from source (optional)
 
-    Clone the project as mentioned above, then run `python3 build_addon.py`, no additional dependency required, only python3 standard library.
+1. Clone the project to download both project and dependencies
 
-2. Or download directly the addon from [release](https://graphics.rwth-aachen.de:9000/hhui/blendertool/-/releases) page. 
+```shell
+git clone https://www.graphics.rwth-aachen.de:9000/hhui/blendertool  --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.
 
-After getting the .zip file, install and enable it using blender addon system. See [here](https://docs.blender.org/manual/en/latest/editors/preferences/addons.html#installing-add-ons) for more details.
+```shell
+python3 build_addon.py
+```
 
+### 1.2 Install Addon
 
-Note: 
-1. You need to restart blender after enabling, otherwise some functionality may not work well.
-2. don't forget to remove the old version of this addon (if present), before adding new version of this addon to blender. (Actually, I not very sure if it's necessary, but I think this would be better)
+After obtaining an installable `.zip` file either from the releases page or from manually building the addon, this should be installed into blender. For more information on how to install addons see [here](https://docs.blender.org/manual/en/latest/editors/preferences/addons.html#installing-add-ons) for more details.
 
+### 1.3 FAQs
 
-### 2.1 Complicated way
+1. You may need to restart blender after enabling the addon for the first time, otherwise some functionality may not work. Technically this should not be **required**, but might be necessary in some untested versions of Blender.
 
-If you want to keep developing on this addon, it would be easier to create a soft link(or Symlinks on windows) at the root directory to the dependencies.
+2. You may have to manually remove old versions of this addon (if present), before installing a new version into Blender. This should rarely be the case but might be the cause of some confusing error messages and issues.
 
+## 2. How to use
 
-## 3. How to use
+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.
 
-After installing addon, you can find it here. (Or simply press `n` key)
+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)
 
 Then you can find it here.
 
 ![homepage](images/1.png)
 
-### 3. Load the animation sequence you want.
+### 2. Load the animation sequence you want
 
-#### 3.1
-you can select the directory through GUI, by clicking the rightmost icon. It will pop up the default blender file explorer. Then you can go to the directory you want, for example, like image showed below. **You only need to go to the directory, then select nothing, just click "Accept"**.
+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)
 
-Then the addon will automatically detect the sequencens it finds in this directory, then you simply select the sequence you want.
+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)
 
-##### 3.1.1
-There is a small checkbox about whether using `relative path` or not.
+#### 2.1 Absolute vs. Relative Paths
 
-when toggling on, then you must save the blender file first, before load the sequence. Then this sequence will be loaded using relative path, from the .blend file. Also if you move the .blend file and data altogether to another directory, it still works.
+There is a small checkbox about whether to use `relative paths` or not.
 
-If not toggling on, it will use abosulte path to load the sequence. And you don't need to save the .blend file.
+When toggled on, the blender file must be saved before loading the sequence. Then this sequence will be loaded using 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.
 
-![relative_path](images/4.png)
+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)
 
-#### 3.2
+#### 2.2 Sequence List View
 
-After the sequence being imported, it will be available in the `Sequences Imported` panel, and more details will be available in `Settings` panel.
+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)
 
-Now, you can play/render the animation as usual.
+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 render the animation, please turn on the `Lock Interface`. 
+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)
 
-##### 3.2.1 Enable/ Disable
+##### 2.2.1 Enable/ Disable
 
-By `enable` means, that the sequence will be updated for each frame, and `disable` means that the sequence won't be updated for each frame, so it can save some computational resources if needed.
+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.
 
-##### 3.2.1 Refresh Sequence
+##### 2.2.1 Refresh Sequence
 
-`Refresh Sequence` can be usefull, when you import the sequence, while the data is still being generated, and not finished yet. Refresh can detect the frames added after being imported.
+`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.
 
-#### 3.3 Settings
+#### 2.3 Settings
 
-#### 3.3.1 Geometry Nodes
+#### 2.3.1 Geometry Nodes
 
-We provide some basic templates for the geometry nodes, especially for the particeles/vertices-only data. 
+While all files are imported as plain geometry, we provide some templates that we have found to be incredibly useful for visualizing particle data.
 
-Applying `Point Cloud` geometry nodes, can convert the the vertices of the mesh to point clouds, which can be rendered only by [cycles](https://docs.blender.org/manual/en/latest/render/cycles/introduction.html).
+Applying the `Point Cloud` geometry node, the vertices of the mesh are converted to a point cloud, which can be rendered only by [cycles](https://docs.blender.org/manual/en/latest/render/cycles/introduction.html) and only as spheres. The exact geometry node setup can be seen in the geometry nodes tab and may be modified as desired, e.g. to set the particle radius.
 
-Applying `Instances` geometry nodes, can convert the the vertices of the mesh to cubes, or others by adjusting the geometry nodes, 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).
+Applying `Instances` geometry nodes, 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). The exact geometry node setup can be seen in the geometry nodes tab and may be modified as desired, e.g. to set the particle radius and to change the instanced geometry. **CAUTION: Because this node setup relies on the `Realize Instances` node, the memory usage increases extremely rapidly. Make sure to save the `.blend` file before attempting this, as Blender may run out of memory!!!**
 
+Applying the `Mesh` geometry node will restore the default geometry nodes, which simply display the imported geometry as it is.
 
-Applying `Mesh` geometry nodes, will use the default geoemtry ndoes.
+Notes:
 
-Note: 
 1. `Instances` is super memory hungry compared with `Point Cloud`.
-2. After applying `Point Cloud` or `Instances` geoemtry 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` geoemtry nodes.
+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)
 
+#### 2.3.2 Path Information
 
-#### 3.3.2 Path Information
-
-Here shows the path of this sequence, however it's not editable.
+This shows the path of the sequence for debugging purposes, however it's not editable.
 
-#### 3.3.3 Attributes Settings
+#### 2.3.3 Attributes Settings
 
-Here shows the available **Vertex Attributes**, it's not editable.
+This panel shows the available **Vertex Attributes**, it's not editable.
 
-Note: in order to avoid the conflication with blender built-in attributes, so all the attributes names are renamed by adding a `2` at the end. For example, `id` -> `id2`. 
+Note: In order to avoid conflicts with Blenders built-in attributes, all the attributes names are renamed by prefixing `bseq_`. For example, `id` -> `bseq_id`. Keep this in mind when accessing attributes in the shader editor.
 
-#### 3.3.4 Split Norm per Vertex
+#### 2.3.4 Split Norm per Vertex
 
-For more details, you can find it [here](https://docs.blender.org/manual/en/latest/modeling/meshes/structure.html#modeling-meshes-normals-custom). This is an easy way to set the selected vertex attribute as this split normal.
+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).
 
-Note: 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 int, then it will give a runtime error.
+Note: 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 int instead of float, then Blender will simply give a runtime error.

__init__.py

@@ -1,7 +1,7 @@
 bl_info = {
-    "name": "Sim Loader",
+    "name": "Sequence Loader",
     "description": "Loader for meshio supported mesh files/ simulation sequences",
-    "author": "Hantao Hui",
+    "author": "Interactive Computer Graphics",
     "version": (1, 0),
     "blender": (3, 1, 0),
     "warning": "",
@@ -46,7 +46,7 @@
 
 
 def register():
-    bpy.app.handlers.load_post.append(SIMLOADER_initilize)
+    bpy.app.handlers.load_post.append(SIMLOADER_initialize)
     for cls in classes:
         bpy.utils.register_class(cls)
     bpy.types.TEXT_MT_templates.append(draw_template)
@@ -66,7 +66,7 @@ def unregister():
     bpy.types.TEXT_MT_templates.remove(draw_template)
     del bpy.types.Scene.SIMLOADER
     del bpy.types.Object.SIMLOADER
-    bpy.app.handlers.load_post.remove(SIMLOADER_initilize)
+    bpy.app.handlers.load_post.remove(SIMLOADER_initialize)
     unsubscribe_to_selected()
 
 

build_addon.py

@@ -22,7 +22,7 @@
 }
 
 today = str(date.today())
-with ZipFile(f'simloader_addon_{today}.zip', 'w') as addonzip:
+with ZipFile(f'blender_sequence_loader_{today}.zip', 'w') as addonzip:
     #  write all directories
     for k, v in dirs.items():
         for subdir, dirs, files in os.walk(k):