Skip to content

Language Improvements #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 1, 2022
Merged

Language Improvements #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5515207
language fixes
digitalillusions Nov 30, 2022
38da7a3
remove warning, because the driver system was fixed after all
digitalillusions Dec 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 10 additions & 11 deletions docs/about.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,29 @@
# 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).
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.
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
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 modify the `sys.path` variable of Blender python environment. It will add the path of this addon into `sys.path`.

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| 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|
| 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

Expand Down
13 changes: 5 additions & 8 deletions docs/build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
# Build and install the addon


## Build from source


1. Clone the project to download both project and dependencies

```shell
Expand All @@ -19,11 +17,11 @@ 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
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 [here](https://docs.blender.org/manual/en/latest/editors/preferences/addons.html#installing-add-ons) for installing and enabling the addon.
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

Expand All @@ -39,17 +37,16 @@ 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,
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).

[^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).

5 changes: 5 additions & 0 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,11 @@

html_theme = "sphinx_rtd_theme"
html_static_path = ['_static']
source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'markdown',
'.md': 'markdown',
}


myst_heading_anchors = 2
4 changes: 2 additions & 2 deletions docs/format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,12 +43,12 @@ The additionally supported file formats are

## 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.
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.
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.
18 changes: 0 additions & 18 deletions docs/frame.md
View file
Open in desktop

This file was deleted.

20 changes: 20 additions & 0 deletions docs/frame.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
Frame control
=============

You can use Blenders `driver system <https://docs.blender.org/manual/en/latest/animation/drivers/index.html>`_ to control the frame of the sequence.

Default settings
*****************

Each sequence has its own property ``Current Frame`` to control its frame. By default, the value equals to the `blender current frame <https://docs.blender.org/manual/en/latest/editors/timeline.html#frame-controls>`_.

.. image:: ../images/current_frame.png
:align: center

Change the value
*****************

Right click on the ``Current Frame`` property, then click ``Edit Driver``. You can check `here <https://docs.blender.org/manual/en/latest/animation/drivers/drivers_panel.html>`_ for more details about how to edit the driver.

.. image:: ../images/edit_driver.png
:align: center
16 changes: 8 additions & 8 deletions docs/global.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
# Global Settings

There are two global settings
1. Print information: default on
1. Auto Refresh: default off

1. Print information: default `true`
1. Auto Refresh: default `false`

## 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.
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 name `bseq_{time}`, `{time}` is the time when rendering starts.
The file has the naming pattern `bseq_{time}`, where `{time}` is the time when rendering is started.

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]
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 toggled, it will [refresh](./list.md#refresh) **all the sequence whenever frame changes**.
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 added after being imported.
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)
15 changes: 7 additions & 8 deletions docs/list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,35 +2,34 @@

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.
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]: Or maybe not, I am not 100% percent sure about this.
[^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 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.
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 change individual sequence, you can click on the `ENABLED` or `DISABLED` button in the list view.
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, then click `Enable Selected` or `Disable Selected` to enable/disable all selected objects.

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 find it [here](./frame.md).
`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.
`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.
Loading