Line Segment Support, Option to only show available frames, Updated README (#31)

* Added support for line segments

* Added a toggle for only showing existent frames at the correct frames

* Updated README and some pictures

* Updated some tooltips

Author: justo46

Diff for: README.md

@@ -86,94 +86,157 @@ After obtaining an installable `.zip` file either from the releases page or from
 
 ## 2. 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.
+**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.
 
-After installing addon, you can find it in the toolbar, which is accessible here or toggled by pressing the `n` key.
+![lock interface](images/lock.png)
+
+After installing addon, you can find it in the toolbar, which is accessible here or toggled by pressing the `N` key.
 
 ![drag](images/drag.png)
 
 Then you can find it here.
 
 ![homepage](images/location.png)
 
-### 2. Load the animation sequence you want
+### 1. Load the animation sequence you want
+
+The easiest way to import sequences is to use the large "Import Sequences" button. After pressing it, you can select as many sequences as you want which will be imported to the scene after pressing `Accept`.
+
+#### 1.1 Relative Paths
+
+The first option is the "Relative Path" option which is turned off by default, i.e. it uses absolute paths by default. 
+
+To enable this option, the blender file has to be saved first. Then the sequences that are imported will be referenced using relative paths 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. 
+
+To change the "Root Directory" to be somewhere else please have a look at the "Global Settings" section.
+
+#### 1.2 Import Default Normals
+
+The sequence loader tries to look for already stored normals that have to meet certain criteria depending on the file types. Currently supported are .obj and .vtk.
+
+For .obj: 
+- Normals have to be normalized to 1. Vertex normals as well as face vertex normals (each vertex can have a different normal for each face) are supported.
+- Any normals are stored by using "vn". Vertex normals are simply referenced in the same order as the vertices and for face vertex normals, the respective index of the normal is stated in the third position where the vertex is referenced for face (e.g. 1/2/3 or 1//3 would reference the 3rd normal for the 1st vertex in some face).
+
+For .vtk: 
+- Only verex normals are supported. They have to be named "normals".
+
+#### 1.3 Custom Transformation Matrix
+
+When enabling this option, you can define a custom transformation matrix (using XYZ Euler Angles) that will be applied once when importing a sequence.
 
-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.**
+#### 1.4 Load sequences from folder (Legacy importer)
 
-![directory](images/directory.png)
+You can select the directory in which your data is located through the GUI by clicking the folder icon. It will open the default blender file explorer. Then, when you are in the desired folder, click `Accept`. You can't select any files in this GUI.
 
-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.
+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 enable the "Custom Pattern" option to enter a manual pattern, where a single `@` character is used to denote a running frame index.
+
+The refresh button simply looks again for sequences in the selcted folder, in case there were any changes made.
+
+Then click the `Load` Sequence" button to load the selected sequence or the `Load All` button to load all found sequences.
 
 ![sequence](images/sequence.png)
 
-#### 2.1 Absolute vs. Relative Paths
+### 2. Global Settings
 
-There is a small checkbox about whether to use `relative paths` or not.
+#### 2.1 Root Directory
 
-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.
+This is where a new root directory can be set. All relative paths will be relative to this directory. If left empty, the file path of the Blender file will be used.
 
-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.
+#### 2.2 Print Sequence Information
 
-![relative_path](images/path.png)
+Print some useful information during rendering in a file located in the same folder as the render output and in the console. For the latter, Blender has to be started from the console. 
 
-#### 2.2 Sequence List View
+#### 2.3 Auto Refresh Active Sequences
 
-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.
+Automatically refresh all active sequences whenever the frame changes. See "Refresh Sequence" for further explanations. This can be useful when generating a sequence and rendering is done simultaneously.
 
-![settings](images/list.png)
+#### 2.4 Auto Refresh All Sequences
 
-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.
+Like the above but with all sequences.
 
-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.
+### 3. Sequence List View
 
-![lock interface](images/lock.png)
+After the sequence being imported, it will be available in the `Sequences` panel, with more settings being available in `Sequence Settings` panel once a sequence has been selected.
+
+![settings](images/list.png)
+
+For each sequence we show the name, a button that shows whether a sequence is active or inactive (this button is clickable, see the next section for more details on the functionality), the current frame number which is also driver that can be edited as well as the smallest and largest number of the respective sequence.
 
-##### 2.2.1 Enable/ Disable
+##### 3.1 Activate / Deactivate Sequences
 
-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.
+It is possible to individually activate or deactivate 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.
+`Activated` means, that the sequence will be updated on frame change, and `Deactivated` means that the sequence won't be updated on frame change.
 
-##### 2.2.1 Refresh Sequence
+##### 3.2 Refresh Sequence
 
 `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.
 
-#### 2.3 Settings
+#### 3.3 Activate / Deactivate All
 
-#### 2.3.1 Geometry Nodes
+Activate or deactivate all sequences shown in the sequences view.
 
-While all files are imported as plain geometry, we provide some templates that we have found to be incredibly useful for visualizing particle data.
+#### 3.4 Set Timeline
 
-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.
+Sets the Blender timeline to range of the smallest to largest number of a file of the selected sequence.
 
-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!!!**
+### 4. Sequence Properties
 
-Applying the `Mesh` geometry node will restore the default geometry nodes, which simply display the imported geometry as it is.
+#### 4.1 Match Blender Frame Numbers
 
-Notes:
+This shows the file of a sequence at the frame number exactly matching the number in the file, otherwise it will not show anything. So if a file sequence goes from 2-10 and 15-30 only at these frames the respective files will be shown.
 
-1. `Instances` is super memory hungry compared with `Point Cloud`.
-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.
+By default this option is turned off and the sequence starts in Blender from 0 and on each following frame the next available file is loaded. For frame number larger than the length of the file sequence, this procedure is looped.
 
-![material](images/geometry_nodes.png)
+#### 4.2 Path
+
+The path of the file sequence is shown here and can also be edited. Relative paths start with // which basically is placeholder for the root directory.
+
+#### 4.3 Pattern
+
+Here you can see and edit the pattern of a file sequence that is used to detect the sequence as well as to determine how many frames the sequence has. A pattern consists of the name, then the frame range followed by an @ and at last, the file extension.
+
+#### 4.4 Current File
 
-#### 2.3.2 Path Information
+This is read-only and shows the absolute path of the file that is currenlty loaded from the selected sequence.
 
-This shows the path of the sequence for debugging purposes, however it's not editable.
+#### 4.5 Last Loading Time
 
-#### 2.3.3 Attributes Settings
+Read-only field, that shows how long it took to load the current file in milliseconds.
+
+#### 4.6 Attributes Settings
 
 This panel shows the available **Vertex Attributes**, it's not editable.
 
 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.
 
-#### 2.3.4 Split Norm per Vertex
+#### 4.6.1 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).
 
 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.
 
-#### 2.3.5 Advanced Settings
+### 5. Advanced Settings
+
+#### 5.1 Script
+
+Here you can import your own script for loading and preprocessing your file sequences. For more information look at the teplate.py file under Scripting -> Templates -> Sequence Loader -> Template.
+
+#### 5.2 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.
+
+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, 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!!!**
 
-TODO
+Applying the `Mesh` geometry node will restore the default geometry nodes, which simply display the imported geometry as it is.
+
+Notes:
+
+1. `Instances` is super memory hungry compared with `Point Cloud`.
+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/geometry_nodes.png)

Diff for: bseq/importer.py

@@ -4,13 +4,17 @@
 import traceback
 import fileseq
 import os
-from .utils import show_message_box, get_relative_path, get_absolute_path
+from .utils import show_message_box, get_relative_path, get_absolute_path, load_meshio_from_path
 import numpy as np
 from mathutils import Matrix
 import time
 # this import is not useless
 import additional_file_formats
 
+def extract_edges(cell: meshio.CellBlock):
+    if cell.type == "line":
+        return cell.data.astype(np.uint64)
+    return np.array([])
 
 def extract_faces(cell: meshio.CellBlock):
     if cell.type == "triangle":
@@ -51,6 +55,8 @@ def extract_faces(cell: meshio.CellBlock):
         return faces
     elif cell.type == "vertex":
         return np.array([])
+    elif cell.type == "line":
+        return np.array([])
     show_message_box(cell.type + " is unsupported mesh format yet")
     return np.array([])
 
@@ -124,21 +130,27 @@ def update_mesh(meshio_mesh, mesh):
         mesh.update()
         mesh.validate()
         return
+    edges = np.array([], dtype=np.uint64)
     faces_loop_start = np.array([], dtype=np.uint64)
     faces_loop_total = np.array([], dtype=np.uint64)
     loops_vert_idx = np.array([], dtype=np.uint64)
     shade_scheme = False
     if mesh.polygons:
         shade_scheme = mesh.polygons[0].use_smooth
+
     for cell in meshio_mesh.cells:
-        data = extract_faces(cell)
-        # np array can't be simply written as `if not data:`,
-        if not data.any():
-            continue
-        n_poly += len(data)
-        n_loop += data.shape[0] * data.shape[1]
-        loops_vert_idx = np.append(loops_vert_idx, data.ravel())
-        faces_loop_total = np.append(faces_loop_total, np.ones((len(data)), dtype=np.uint64) * data.shape[1])
+        edge_data = extract_edges(cell)
+        face_data = extract_faces(cell)
+
+        if edge_data.any():
+            edges = np.append(edges, edge_data)
+
+        if face_data.any():
+            n_poly += len(face_data)
+            n_loop += face_data.shape[0] * face_data.shape[1]
+            loops_vert_idx = np.append(loops_vert_idx, face_data.ravel())
+            faces_loop_total = np.append(faces_loop_total, np.ones((len(face_data)), dtype=np.uint64) * face_data.shape[1])
+
     if faces_loop_total.size > 0:
         faces_loop_start = np.cumsum(faces_loop_total)
         # Add a zero as first entry
@@ -150,18 +162,20 @@ def update_mesh(meshio_mesh, mesh):
     else:
         mesh.clear_geometry()
         mesh.vertices.add(n_verts)
+        mesh.edges.add(len(edge_data))
         mesh.loops.add(n_loop)
         mesh.polygons.add(n_poly)
 
     mesh.vertices.foreach_set("co", mesh_vertices.ravel())
+    mesh.edges.foreach_set("vertices", edges)
     mesh.loops.foreach_set("vertex_index", loops_vert_idx)
     mesh.polygons.foreach_set("loop_start", faces_loop_start)
     mesh.polygons.foreach_set("loop_total", faces_loop_total)
     mesh.polygons.foreach_set("use_smooth", [shade_scheme] * len(faces_loop_total))
 
     # newer function but is about 4 times slower
     # mesh.clear_geometry()
-    # mesh.from_pydata(mesh_vertices, [], data)
+    # mesh.from_pydata(mesh_vertices, edge_data, face_data)
 
     mesh.update()
     mesh.validate()
@@ -202,7 +216,7 @@ def update_mesh(meshio_mesh, mesh):
             indices = [item for sublist in meshio_mesh.cell_data["obj:vn_face_idx"][0] for item in sublist]
             mesh.normals_split_custom_set([meshio_mesh.field_data["obj:vn"][i - 1] for i in indices])
 
-# function to create a single meshio object
+# function to create a single meshio object (not a sequence, this just inports some file using meshio)
 def create_meshio_obj(filepath):
     meshio_mesh = None
     try:
@@ -316,16 +330,18 @@ def update_obj(scene, depsgraph=None):
             finally:
                 del locals()['preprocess']
         else:
-            filepath = fs[current_frame % len(fs)]
-            filepath = os.path.normpath(filepath)
-            try:
-                meshio_mesh = meshio.read(filepath)
-                obj.BSEQ.current_file = filepath
-            except Exception as e:
-                show_message_box("Error when reading: " + filepath + ",\n" + traceback.format_exc(),
-                                 "Meshio Loading Error" + str(e),
-                                 icon="ERROR")
-                continue
+            if obj.BSEQ.match_frames:
+                fs_frames = fs.frameSet()
+                if current_frame in fs_frames:
+                    filepath = fs[fs_frames.index(current_frame)]
+                    filepath = os.path.normpath(filepath)
+                    meshio_mesh = load_meshio_from_path(fs, filepath, obj)
+                else:
+                    meshio_mesh = meshio.Mesh([], [])
+            else:
+                filepath = fs[current_frame % len(fs)]
+                filepath = os.path.normpath(filepath)
+                meshio_mesh = load_meshio_from_path(fs, filepath, obj)
 
         if not isinstance(meshio_mesh, meshio.Mesh):
             show_message_box('function preprocess does not return meshio object', "ERROR")