@volter/blender-engine 0.1.147 → 0.1.149

package/browser/addons/vrm/common/workspace.py

@@ -0,0 +1,227 @@
+# SPDX-License-Identifier: MIT OR GPL-3.0-or-later
+import sys
+from collections.abc import Generator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import bpy
+from bpy.types import Context, Object
+from mathutils import Matrix
+
+from .logger import get_logger
+
+_logger = get_logger(__name__)
+
+
+@dataclass(frozen=True)
+class SavedWorkspace:
+    # Be careful not to include objects that might disappear before and after yield
+    cursor_matrix: Matrix
+    previous_object_name: Optional[str]
+    previous_object_mode: Optional[str]
+    active_object_name: Optional[str]
+    active_object_hide_viewport: bool
+
+
+def _enter_save_workspace(
+    context: Context, obj: Optional[Object] = None, *, mode: str = "OBJECT"
+) -> SavedWorkspace:
+    # Save the position of the 3D cursor
+    cursor_matrix = context.scene.cursor.matrix.copy()
+
+    previous_object_name = None
+    previous_object_mode = None
+    previous_object = context.view_layer.objects.active
+    if previous_object:
+        # previous_object may disappear after yield.
+        # We intern it just in case, but it might not be necessary.
+        previous_object_name = sys.intern(previous_object.name)
+        previous_object_mode = sys.intern(previous_object.mode)
+
+        # If an obj argument is passed, set the mode to "OBJECT". If the mode
+        # stays as is, it may not be possible to change the active object
+        if previous_object != obj and previous_object_mode != "OBJECT":
+            previous_object_hide_viewport = previous_object.hide_viewport
+            if previous_object_hide_viewport:
+                # If hide_viewport is True, mode_set may fail if left as is
+                previous_object.hide_viewport = False
+            bpy.ops.object.mode_set(mode="OBJECT")
+            if previous_object.hide_viewport != previous_object_hide_viewport:
+                previous_object.hide_viewport = previous_object_hide_viewport
+
+    # If an object is passed, make it active
+    if obj is not None:
+        context.view_layer.objects.active = obj
+        context.view_layer.update()
+
+    active_object_name = None
+    active_object_hide_viewport = False
+    # Change the mode of the active object
+    active_object = context.view_layer.objects.active
+    if active_object:
+        # active_object may disappear after yield.
+        # We intern it just in case, but it might not be necessary.
+        active_object_name = sys.intern(active_object.name)
+        active_object_hide_viewport = active_object.hide_viewport
+        # If hide_viewport is True, mode_set may fail if left as is
+        # Currently we force it to be visible even when not changing mode,
+        # but this may be inappropriate
+        if active_object_hide_viewport:
+            active_object.hide_viewport = False
+        if active_object.mode != mode:
+            bpy.ops.object.mode_set(mode=mode)
+
+    return SavedWorkspace(
+        cursor_matrix=cursor_matrix,
+        previous_object_name=previous_object_name,
+        previous_object_mode=previous_object_mode,
+        active_object_name=active_object_name,
+        active_object_hide_viewport=active_object_hide_viewport,
+    )
+
+
+def _exit_save_workspace(context: Context, saved_workspace: SavedWorkspace) -> None:
+    cursor_matrix = saved_workspace.cursor_matrix
+    previous_object_name = saved_workspace.previous_object_name
+    previous_object_mode = saved_workspace.previous_object_mode
+    active_object_name = saved_workspace.active_object_name
+    active_object_hide_viewport = saved_workspace.active_object_hide_viewport
+
+    previous_object = None
+    if previous_object_name is not None:
+        previous_object = context.blend_data.objects.get(previous_object_name)
+
+    current_active_object = context.view_layer.objects.active
+
+    # Set the mode of the currently active object to "OBJECT". If the mode stays as is,
+    # it may not be possible to change the active object
+    if (
+        current_active_object
+        and current_active_object != previous_object
+        and current_active_object.mode != "OBJECT"
+    ):
+        current_active_object_hide_viewport = current_active_object.hide_viewport
+        if current_active_object.hide_viewport:
+            current_active_object.hide_viewport = False
+        bpy.ops.object.mode_set(mode="OBJECT")
+        if current_active_object.hide_viewport != current_active_object_hide_viewport:
+            current_active_object.hide_viewport = current_active_object_hide_viewport
+
+    # Restore the hide_viewport of the activated object
+    if active_object_name is not None:
+        active_object = context.blend_data.objects.get(active_object_name)
+        if active_object and active_object.hide_viewport != active_object_hide_viewport:
+            active_object.hide_viewport = active_object_hide_viewport
+
+    # Return to the originally active object
+    previous_object = None
+    if previous_object_name is not None:
+        previous_object = context.blend_data.objects.get(previous_object_name)
+
+    if context.view_layer.objects.active != previous_object:
+        context.view_layer.objects.active = previous_object
+        context.view_layer.update()
+
+    # Restore the mode of the originally active object
+    if (
+        previous_object
+        and previous_object_mode is not None
+        and previous_object_mode != previous_object.mode
+    ):
+        # If hide_viewport is True, mode_set may fail if left as is
+        # Restore hide_viewport after mode_set is completed
+        previous_object_hide_viewport = previous_object.hide_viewport
+        if previous_object_hide_viewport:
+            previous_object.hide_viewport = False
+        bpy.ops.object.mode_set(mode=previous_object_mode)
+        if previous_object.hide_viewport != previous_object_hide_viewport:
+            previous_object.hide_viewport = previous_object_hide_viewport
+
+    # Restore the 3D cursor position
+    context.scene.cursor.matrix = cursor_matrix
+
+
+@contextmanager
+def save_workspace(
+    context: Context, obj: Optional[Object] = None, *, mode: str = "OBJECT"
+) -> Generator[None]:
+    saved_workspace = _enter_save_workspace(context, obj, mode=mode)
+    try:
+        yield
+        # After yield, bpy native objects may be deleted or become invalid
+        # as frames advance. Accessing them in this state can cause crashes,
+        # so be careful not to access potentially invalid native objects
+        # after yield
+    finally:
+        _exit_save_workspace(context, saved_workspace)
+
+
+def wm_append_without_library(
+    context: Context,
+    blend_path: Path,
+    *,
+    append_filepath: str,
+    append_filename: str,
+    append_directory: str,
+) -> set[str]:
+    """Call wm.append and remove the added libraries.
+
+    Used to work around the issue where wm.append adding libraries causes
+    asset library addition to fail.
+    https://github.com/saturday06/VRM-Addon-for-Blender/issues/631
+    https://github.com/saturday06/VRM-Addon-for-Blender/issues/646
+    """
+    # https://projects.blender.org/blender/blender/src/tag/v2.93.18/source/blender/windowmanager/intern/wm_files_link.c#L85-L90
+    with save_workspace(context):
+        # List of pointers for library addition detection.
+        # Used only for addition detection. Be careful not to dereference,
+        # as it is dangerous.
+        existing_library_pointers: list[int] = [
+            library.as_pointer() for library in context.blend_data.libraries
+        ]
+
+        result = bpy.ops.wm.append(
+            filepath=append_filepath,
+            filename=append_filename,
+            directory=append_directory,
+            link=False,
+        )
+        if result != {"FINISHED"}:
+            return result
+
+        # Remove one added library.
+        # Reverse order to handle recursive calls, but effectiveness is unconfirmed.
+        for library in reversed(list(context.blend_data.libraries)):
+            try:
+                library_path = Path(bpy.path.abspath(library.filepath))
+                if not library_path.exists() or not blend_path.samefile(library_path):
+                    continue
+            except OSError:
+                message = f'Failed to access library path for "{library.name}"'
+                _logger.warning(message)
+                continue
+
+            if library.as_pointer() in existing_library_pointers:
+                continue
+
+            if bpy.app.version >= (3, 2) and library.use_extra_user:
+                library.use_extra_user = False
+            if library.users:
+                if bpy.app.version >= (3, 2):
+                    _logger.warning(
+                        'Failed to remove "%s" with %d users'
+                        " while appending blend file:"
+                        ' filepath="%s" filename="%s" directory="%s"',
+                        library.name,
+                        library.users,
+                        append_filepath,
+                        append_filename,
+                        append_directory,
+                    )
+            else:
+                context.blend_data.libraries.remove(library)
+
+            break
+        return result

package/browser/addons/vrm/common/writable_context.py

@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: MIT OR GPL-3.0-or-later
+
+from dataclasses import dataclass, field
+from typing import Final, Optional, Protocol
+
+import bpy
+from bpy.app.handlers import persistent
+from bpy.types import Context
+
+
+class WritableContextBecomesAvailableOnceHandler(Protocol):
+    def __call__(self, context: Context, *, load_post: bool) -> None: ...
+
+
+@dataclass
+class State:
+    registered_handlers: Final[list[WritableContextBecomesAvailableOnceHandler]] = (
+        field(default_factory=list[WritableContextBecomesAvailableOnceHandler])
+    )
+    pending_handlers: Final[list[WritableContextBecomesAvailableOnceHandler]] = field(
+        default_factory=list[WritableContextBecomesAvailableOnceHandler]
+    )
+
+
+_state: Final = State()
+
+
+def register_writable_context_becomes_available_once_handler(
+    handler: WritableContextBecomesAvailableOnceHandler,
+) -> None:
+    if handler not in _state.registered_handlers:
+        _state.registered_handlers.append(handler)
+    if handler not in _state.pending_handlers:
+        _state.pending_handlers.append(handler)
+
+    if not bpy.app.timers.is_registered(
+        _writable_context_becomes_available_timer_callback
+    ):
+        bpy.app.timers.register(_writable_context_becomes_available_timer_callback)
+
+
+def _writable_context_becomes_available_timer_callback() -> Optional[float]:
+    context = bpy.context
+    trigger_writable_context_becomes_available_once_handlers(context, load_post=False)
+
+
+def trigger_writable_context_becomes_available_once_handlers(
+    context: Context, *, load_post: bool
+) -> None:
+    try:
+        while _state.pending_handlers:
+            handler = _state.pending_handlers.pop()
+            handler(context, load_post=load_post)
+    finally:
+        _state.pending_handlers.clear()
+
+
+@persistent
+def load_post(_unused: object) -> None:
+    context = bpy.context
+    for handler in _state.registered_handlers:
+        if handler not in _state.pending_handlers:
+            _state.pending_handlers.append(handler)
+    trigger_writable_context_becomes_available_once_handlers(context, load_post=True)
+
+
+@persistent
+def depsgraph_update_pre(_unused: object) -> None:
+    context = bpy.context
+    trigger_writable_context_becomes_available_once_handlers(context, load_post=False)
+
+
+def clear_writable_context_becomes_available_once_handlers() -> None:
+    _state.registered_handlers.clear()
+    _state.pending_handlers.clear()
+    if bpy.app.timers.is_registered(_writable_context_becomes_available_timer_callback):
+        bpy.app.timers.unregister(_writable_context_becomes_available_timer_callback)

package/browser/addons/vrm/documentation/en-us/animation/index.md

@@ -0,0 +1,63 @@
+---
+title: "VRM Animation"
+description: "How to import and export VRM Animation files."
+---
+
+This section explains how to import and export VRM Animation files.
+
+![](/assets/images/animation.gif)
+
+An English tutorial is currently being written.
+
+---
+
+VRM Animationのインポートとエクスポートの解説です。
+
+## VRM Animationファイルのエクスポート
+
+VRM Animationのエクスポートには、VRM
+1.0のアーマチュアが必要です。エクスポートされるアニメーションは次の通りです
+
+- Humanoidボーンの回転値
+- Humanoid Hipsボーンの移動値
+- Expressionのプレビュー値 (Look At値のエクスポートは現在未対応)
+
+最低限のアニメーションをエクスポートしてみます。
+
+![](1.png)
+
+![](2.png)
+
+![](3.png)
+
+![](4.png)
+
+![](5.png)
+
+![](6.png)
+
+![](7.png)
+
+![](8.png)
+
+![](9.png)
+
+![](10.png)
+
+![](11.png)
+
+![](12.png)
+
+![](13.png)
+
+![](14.png)
+
+![](15.png)
+
+## VRM Animationファイルのインポート
+
+![](16.png)
+
+![](17.png)
+
+![](18.png)

package/browser/addons/vrm/documentation/en-us/create-humanoid-vrm-from-scratch/index.md

@@ -0,0 +1,131 @@
+---
+title: "Create Humanoid VRM"
+description: "We will create a simple Humanoid VRM model."
+---
+
+We will create a simple Humanoid VRM model.
+
+![](/assets/images/humanoid.gif)
+
+After starting Blender, place the mouse cursor on the 3D Viewport and press the
+`n` key.
+
+![](1.png)
+
+This will open a Sidebar from the right side. Select the `VRM` tab and click the
+`Create VRM Model` button.
+
+![](2.png)
+
+Then an armature suitable for VRM output will be created automatically. An
+armature represents the bone structure of a 3D model. This add-on uses armature
+to represent the skeletal structure of the human figure in VRM.
+
+![](3.png)
+
+We will use the default Cube as a torso.
+
+Select the Cube in the 3D Viewport, select the tab with the
+"![](/assets/images/object_property_tab_icon.png)" icon in the lower right
+corner, go to `Transform` > `Scale`, and set all values to `0.2` to make it
+small enough to be used as a torso.
+
+![](4.png)
+
+We associate the torso with the bones of the armature. Go to `Relations`, and
+set `Parent` to `Armature`, `Parent Type` to `Bone`, and `Parent Bone` to
+`spine`. The torso will move to the spine of the 3D model.
+
+![](5.png)
+
+The next step is to create the head, press `Shift + a` in the 3D viewport to
+bring up an additional menu, select `Mesh` -> `UV Sphere`.
+
+![](6.png)
+
+A `Sphere` will be added.
+
+![](7.png)
+
+It is too big so we will shrink it.
+
+Select the tab with the "![](/assets/images/object_property_tab_icon.png)" icon
+in the lower right corner, go to `Transform` > `Scale`, and set all values to
+`0.25`.
+
+![](8.png)
+
+Associate this sphere with the armature's bone. Go to `Relations`, and set
+`Parent` to `Armature`, `Parent Type` to `Bone`, and `Parent Bone` to `head`.
+The sphere will move to the head of the 3D model.
+
+![](9.png)
+
+Next, we will add the limbs: in the 3D viewport, press `Shift + a` to bring up
+the Add menu, and select `Mesh` -> `Ico Sphere`.
+
+![](10.png)
+
+The `Icosphere` will be added, and at the same time, you will see
+`> Add Ico Sphere` in the lower-left corner of the 3D viewport. Click on this
+message.
+
+![](11.png)
+
+You can then set up the new Ico Sphere to be added. We feel that the radius is
+too large so we will change the radius value to `0.1 m`.
+
+![](12.png)
+
+Select the tab with the "![](/assets/images/object_property_tab_icon.png)" icon
+in the lower right corner, go to `Relations`, set `Parent` to `Armature`, set
+`Parent Type` to `Bone`, and set `Parent Bone` to `upper_arm.L`. The sphere will
+move to the left upper arm of the 3D model.
+
+![](13.png)
+
+Add the Ico sphere as before, and now associate it with the `hand.L` bone. The
+Ico sphere will move to the left hand.
+
+![](14.png)
+
+Similarly, we will associate it with the `upper_arm.R` bone.
+
+![](15.png)
+
+Associate with the `hand.R` bone.
+
+![](16.png)
+
+Associate with the `upper_leg.L` bone.
+
+![](17.png)
+
+Associate with the `lower_leg.L` bone.
+
+![](18.png)
+
+Associate with the `upper_leg.R` bone.
+
+![](19.png)
+
+Finally, associate it with the `lower_leg.R` bone.
+
+![](20.png)
+
+Save this model as a VRM. Select `File` → `Export` → `VRM (.vrm)` from the menu.
+
+![](21.png)
+
+Enter the filename and destination when the File View window appears and press
+`Export VRM`.
+
+![](22.png)
+
+If successful, the VRM file will be saved to the specified location.
+
+![](/assets/images/humanoid.gif)
+
+You can check the operation on this page.
+
+- https://hub.vroid.com/en/characters/6595382014094436897/models/1372267393572384142

package/browser/addons/vrm/documentation/en-us/create-simple-vrm-from-scratch/index.md

@@ -0,0 +1,30 @@
+---
+title: "Create Simple VRM"
+description: "Convert the cube displayed from the beginning when you start Blender to a VRM model."
+---
+
+Convert the cube displayed from the beginning when you start Blender to a VRM
+model.
+
+![](/assets/images/simple.gif)
+
+First, start Blender and make sure that the cube is displayed.
+
+![](1.png)
+
+Next, select `File` → `Export` → `VRM (.vrm)` from the menu.
+
+![](2.png)
+
+Enter the filename and destination when the File View window appears and press
+`Export VRM`.
+
+![](3.png)
+
+If successful, the VRM file will be saved to the specified location.
+
+![](/assets/images/simple.gif)
+
+You can check the operation on this page.
+
+- https://hub.vroid.com/en/characters/2535511199028537879/models/127230567429676411

package/browser/addons/vrm/documentation/en-us/development/index.md

@@ -0,0 +1,136 @@
+---
+title: "Development How-To"
+description: "Set up the development environment for VRM Add-on for Blender."
+---
+
+Instructions for setting up the add-on development environment.
+
+![](/assets/images/development.gif)
+
+[The repository](https://github.com/saturday06/VRM-Addon-for-Blender) contains
+source code, code formatting settings, code type checking settings, and software
+testing settings. These are strongly dependent on the tool
+[astral-sh/uv](https://docs.astral.sh/uv/), so you will need to install that
+first. Alternatively, you can use [Dev Container](https://containers.dev/) to
+set them up automatically.
+
+## Link the repository to the add-on folder
+
+The
+[src/io_scene_vrm](https://github.com/saturday06/VRM-Addon-for-Blender/tree/main/src/io_scene_vrm)
+folder contains the main add-on code. By creating a symbolic link to this folder
+in Blender's `user_default` or `addons` directory, you can install the
+development source code as an add-on in Blender, making it easy to test changes
+efficiently.
+
+### How to create a development link for Blender 4.2 or later
+
+#### Linux
+
+```sh
+blender_version=4.5
+mkdir -p "$HOME/.config/blender/$blender_version/extensions/user_default"
+ln -Ts "$PWD/src/io_scene_vrm" "$HOME/.config/blender/$blender_version/extensions/user_default/vrm"
+```
+
+#### macOS
+
+```sh
+blender_version=4.5
+mkdir -p "$HOME/Library/Application Support/Blender/$blender_version/extensions/user_default"
+ln -s "$PWD/src/io_scene_vrm" "$HOME/Library/Application Support/Blender/$blender_version/extensions/user_default/vrm"
+```
+
+#### Windows PowerShell
+
+```powershell
+$blenderVersion = "4.5"
+New-Item -ItemType Directory -Path "$Env:APPDATA\Blender Foundation\Blender\$blenderVersion\extensions\user_default" -Force
+New-Item -ItemType Junction -Path "$Env:APPDATA\Blender Foundation\Blender\$blenderVersion\extensions\user_default\vrm" -Value "$(Get-Location)\src\io_scene_vrm"
+```
+
+### How to create a development link for Blender 4.1.1 or earlier
+
+#### Linux
+
+```sh
+blender_version=3.6
+mkdir -p "$HOME/.config/blender/$blender_version/scripts/addons"
+ln -Ts "$PWD/src/io_scene_vrm" "$HOME/.config/blender/$blender_version/scripts/addons/io_scene_vrm"
+```
+
+#### macOS
+
+```sh
+blender_version=3.6
+mkdir -p "$HOME/Library/Application Support/Blender/$blender_version/scripts/addons"
+ln -s "$PWD/src/io_scene_vrm" "$HOME/Library/Application Support/Blender/$blender_version/scripts/addons/io_scene_vrm"
+```
+
+#### Windows PowerShell
+
+```powershell
+$blenderVersion = "3.6"
+New-Item -ItemType Directory -Path "$Env:APPDATA\Blender Foundation\Blender\$blenderVersion\scripts\addons" -Force
+New-Item -ItemType Junction -Path "$Env:APPDATA\Blender Foundation\Blender\$blenderVersion\scripts\addons\io_scene_vrm" -Value "$(Get-Location)\src\io_scene_vrm"
+```
+
+## To format the code, follow these steps
+
+1. Install [astral-sh/uv](https://docs.astral.sh/uv/).
+2. Double-click `tools\format.bat` in the repository to run it.
+
+## To format the code in Visual Studio Code, follow these steps
+
+1. Install the `Ruff` extension in Visual Studio Code.
+2. Run Visual Studio Code's `Format Document`.
+
+## To run type checking of the code, follow these steps
+
+1. Install [astral-sh/uv](https://docs.astral.sh/uv/).
+2. Double-click `tools\lint.bat` in the repository and run it.
+
+## To run type checking of the code in Visual Studio Code, follow these steps
+
+1. Install the `Pyright` extension in Visual Studio Code.
+2. Open the Python file you want to type check.
+
+## To run the software tests of the code, follow these steps
+
+1. Install [astral-sh/uv](https://docs.astral.sh/uv/).
+2. Double-click `tools\test.bat` in the repository and run it.
+
+## To run the software tests of the code in Visual Studio Code, follow these steps
+
+1. Install [astral-sh/uv](https://docs.astral.sh/uv/).
+2. In the Visual Studio Code terminal, run the `uv sync` command.
+3. Select `Testing` from the left icon in Visual Studio Code.
+4. Select `Configure Python Tests`.
+5. Select `unittests` as the test library.
+6. Select `Root Directory` as the test folder.
+7. Select `test_*` as the test file pattern.
+8. Press `Run Tests`.
+
+## How to create a distribution build
+
+You can create a distribution build on Ubuntu Linux LTS.
+
+1. Run the `sudo ./tools/install_ubuntu_packages.sh` command to install the
+   required packages.
+2. Run the `./tools/build_release.sh` command.
+3. If you see the following output, the build was successful:
+
+```text
+|
+| Release Build Completed
+|
+| - Blender 4.2 or later:
+|   /workspace/release_output/VRM_Addon_for_Blender-Extension-0_0_0.zip
+|
+| - Blender 2.93 - 4.1:
+|   /workspace/release_output/VRM_Addon_for_Blender-0_0_0.zip
+|
+```
+
+For more details, refer to the GitHub Actions code at
+https://github.com/saturday06/VRM-Addon-for-Blender/blob/v3.11.5/.github/workflows/release-please.yml#L51-L54.