124 lines
8.9 KiB
Markdown
124 lines
8.9 KiB
Markdown
# Blender Integration Plan: Node Groups from Processed Assets
|
|
|
|
**Objective:** Develop a Python script (`blenderscripts/create_nodegroups.py`) to run manually inside Blender. This script will scan the output directory generated by the Asset Processor Tool, read `metadata.json` files, and create/update corresponding PBR node groups in the active Blender file, leveraging the pre-calculated metadata.
|
|
|
|
**Key Principles:**
|
|
|
|
* **Leverage Existing Tool Output:** Rely entirely on the structured output and `metadata.json` from the Asset Processor Tool. Avoid reprocessing or recalculating data already available.
|
|
* **Blender Environment:** The script is designed solely for Blender's Python environment (`bpy`).
|
|
* **Manual Execution:** Users will manually run this script from Blender's Text Editor.
|
|
* **Target Active File:** All operations modify the currently open `.blend` file.
|
|
* **Assume Templates:** The script will assume node group templates (`Template_PBRSET`, `Template_PBRTYPE`) exist in the active file. Error handling will be added if they are missing.
|
|
* **Focus on Node Groups:** The script's scope is limited to creating and updating the node groups, not materials.
|
|
|
|
**Detailed Plan:**
|
|
|
|
1. **Script Setup & Configuration:**
|
|
* Create a new Python file named `create_nodegroups.py` (intended location: `blenderscripts/`).
|
|
* Import necessary modules (`bpy`, `os`, `json`, `pathlib`).
|
|
* Define user-configurable variables at the top:
|
|
* `PROCESSED_ASSET_LIBRARY_ROOT`: Path to the root output directory of the Asset Processor Tool.
|
|
* `PARENT_TEMPLATE_NAME`: Name of the parent node group template (e.g., `"Template_PBRSET"`).
|
|
* `CHILD_TEMPLATE_NAME`: Name of the child node group template (e.g., `"Template_PBRTYPE"`).
|
|
* `ASPECT_RATIO_NODE_LABEL`: Label of the Value node in the parent template for aspect ratio correction (e.g., `"AspectRatioCorrection"`).
|
|
* `STATS_NODE_PREFIX`: Prefix for Combine XYZ nodes storing stats in the parent template (e.g., `"Histogram-"`).
|
|
* `ENABLE_MANIFEST`: Boolean flag to enable/disable the manifest system (default: `True`).
|
|
|
|
2. **Manifest Handling:**
|
|
* **Location:** Use a separate JSON file named `[ActiveBlendFileName]_manifest.json`, located in the same directory as the active `.blend` file.
|
|
* **Loading:** Implement `load_manifest(context)` that finds and reads the manifest JSON file. If not found or invalid, return an empty dictionary.
|
|
* **Saving:** Implement `save_manifest(context, manifest_data)` that writes the `manifest_data` dictionary to the manifest JSON file.
|
|
* **Checking:** Implement helper functions `is_asset_processed(manifest_data, asset_name)` and `is_map_processed(manifest_data, asset_name, map_type, resolution)` to check against the loaded manifest.
|
|
* **Updating:** Update the manifest dictionary in memory as assets/maps are processed. Save the manifest once at the end of the script.
|
|
|
|
3. **Core Logic - `process_library()` function:**
|
|
* Get Blender context.
|
|
* Load manifest data (if enabled).
|
|
* Validate that `PROCESSED_ASSET_LIBRARY_ROOT` exists.
|
|
* Validate that template node groups exist in `bpy.data.node_groups`. Exit gracefully with an error message if not found.
|
|
* Initialize counters (new groups, updated groups, etc.).
|
|
* **Scan Directory:** Use `os.walk` or `pathlib.rglob` to find all `metadata.json` files within the `PROCESSED_ASSET_LIBRARY_ROOT`.
|
|
* **Iterate Metadata:** For each `metadata.json` found:
|
|
* Parse the JSON data. Extract key information: `asset_name`, `supplier_name`, `archetype`, `maps` (dictionary of maps with resolutions, paths, stats), `aspect_ratio_change_string`.
|
|
* Check manifest if asset is already processed (if enabled). Skip if true.
|
|
* **Parent Group Handling:**
|
|
* Determine target parent group name (e.g., `f"PBRSET_{asset_name}"`).
|
|
* Find existing group or create a copy from `PARENT_TEMPLATE_NAME`.
|
|
* Mark group as asset (`asset_mark()`) if not already.
|
|
* **Apply Metadata:**
|
|
* Find the aspect ratio node using `ASPECT_RATIO_NODE_LABEL`. Calculate the correction factor based on the `aspect_ratio_change_string` from metadata (using helper function `calculate_factor_from_string`) and set the node's default value.
|
|
* For relevant map types (e.g., ROUGH, DISP), find the stats node (`STATS_NODE_PREFIX` + map type). Set the X, Y, Z inputs using the `min`, `max`, `mean` values stored in the map's metadata entry for the reference resolution.
|
|
* **Apply Asset Tags:** Use `asset_data.tags.new()` to add the `supplier_name` and `archetype` tags (checking for existence first).
|
|
* **Child Group Handling (Iterate through `maps` in metadata):**
|
|
* For each `map_type` (e.g., "COL", "NRM") and its data in the metadata:
|
|
* Determine target child group name (e.g., `f"PBRTYPE_{asset_name}_{map_type}"`).
|
|
* Find existing child group or create a copy from `CHILD_TEMPLATE_NAME`.
|
|
* Find the corresponding placeholder node in the *parent* group (by label matching `map_type`). Assign the child node group to this placeholder (`placeholder_node.node_tree = child_group`).
|
|
* Link the child group's output to the corresponding parent group's output socket. Ensure the parent output socket type is `NodeSocketColor`.
|
|
* **Image Node Handling (Iterate through resolutions for the map type):**
|
|
* For each `resolution` (e.g., "4K", "2K") and its `image_path` in the metadata:
|
|
* Check manifest if this specific map/resolution is processed (if enabled). Skip if true.
|
|
* Find the corresponding Image Texture node in the *child* group (by label matching `resolution`, e.g., "4K").
|
|
* Load the image using `bpy.data.images.load(image_path, check_existing=True)`. Handle potential file-not-found errors.
|
|
* Assign the loaded image to the `image_node.image`.
|
|
* Set the `image_node.image.colorspace_settings.name` based on the `map_type` (using a helper function `get_color_space`).
|
|
* Update manifest dictionary for this map/resolution (if enabled).
|
|
* Update manifest dictionary for the processed asset (if enabled).
|
|
* Save manifest data (if enabled and changes were made).
|
|
* Print summary (duration, groups created/updated, etc.).
|
|
|
|
4. **Helper Functions:**
|
|
* `find_nodes_by_label(node_tree, label, node_type)`: Reusable function to find nodes.
|
|
* `calculate_factor_from_string(aspect_string)`: Parses the `aspect_ratio_change_string` from metadata and returns the appropriate UV X-scaling factor.
|
|
* `get_color_space(map_type)`: Returns the appropriate Blender color space name for a given map type string.
|
|
* `add_tag_if_new(asset_data, tag_name)`: Adds a tag if it doesn't exist.
|
|
* Manifest loading/saving/checking functions.
|
|
|
|
5. **Execution Block (`if __name__ == "__main__":`)**
|
|
* Add pre-run checks (templates exist, library path valid, blend file saved if manifest enabled).
|
|
* Call the main `process_library()` function.
|
|
* Include basic timing and print statements for start/end.
|
|
|
|
**Mermaid Diagram:**
|
|
|
|
```mermaid
|
|
graph TD
|
|
A[Start Script in Blender] --> B(Load Config: Lib Path, Template Names, Node Labels);
|
|
B --> C{Check Templates Exist};
|
|
C -- Templates OK --> D(Load Manifest from adjacent .json file);
|
|
C -- Templates Missing --> X(Error & Exit);
|
|
D --> E{Scan Processed Library for metadata.json};
|
|
E --> F{For each metadata.json};
|
|
F --> G{Parse Metadata (Asset Name, Supplier, Archetype, Maps, Aspect Str, Stats)};
|
|
G --> H{Is Asset in Manifest?};
|
|
H -- Yes --> F;
|
|
H -- No --> I{Find/Create Parent Group (PBRSET_)};
|
|
I --> J(Mark as Asset & Apply Supplier + Archetype Tags);
|
|
J --> K(Find Aspect Node & Set Value from Aspect String);
|
|
K --> M{For each Map Type in Metadata};
|
|
M --> N(Find Stats Node & Set Values from Stats in Metadata);
|
|
N --> O{Find/Create Child Group (PBRTYPE_)};
|
|
O --> P(Assign Child to Parent Placeholder);
|
|
P --> Q(Link Child Output to Parent Output);
|
|
Q --> R{For each Resolution of Map};
|
|
R --> S{Is Map/Res in Manifest?};
|
|
S -- Yes --> R;
|
|
S -- No --> T(Find Image Node in Child);
|
|
T --> U(Load Processed Image);
|
|
U --> V(Assign Image to Node);
|
|
V --> W(Set Image Color Space);
|
|
W --> W1(Update Manifest Dict for Map/Res);
|
|
W1 --> R;
|
|
R -- All Resolutions Done --> M;
|
|
M -- All Map Types Done --> X1(Update Manifest Dict for Asset);
|
|
X1 --> F;
|
|
F -- All metadata.json Processed --> Y(Save Manifest Dict to adjacent .json file);
|
|
Y --> Z(Print Summary & Finish);
|
|
|
|
subgraph "Manifest Operations (External File)"
|
|
D; H; S; W1; X1; Y;
|
|
end
|
|
|
|
subgraph "Node/Asset Operations"
|
|
I; J; K; N; O; P; Q; T; U; V; W;
|
|
end |