Relevant source files
The Utility Functions system provides a collection of reusable helper methods that support various operations throughout the MMD UuuNyaa Tools addon. These functions handle common tasks such as data transformation, file system operations, UI rendering, and error handling, enabling consistent behavior across the addon's components.
For information about how these utility functions are used in specific systems like Asset Management, see Asset Management. For integration with armature-related features, see Armature Editing.
Function Categories
The utility functions in MMD UuuNyaa Tools are organized into the following functional categories:
Title: Utility Function Categories
Sources: mmd_uuunyaa_tools/utilities.py
Function Dependencies
Some utility functions depend on or call other functions within the utilities module:
Title: Utility Function Dependencies
Sources: mmd_uuunyaa_tools/utilities.py18-19 mmd_uuunyaa_tools/utilities.py72-76 mmd_uuunyaa_tools/utilities.py92-93
Data Transformation Functions
These functions transform data from one form to another for consistent data handling throughout the addon.
to_int32(value: int) -> int
Converts an integer value to a 32-bit signed integer.
Parameters:
value: The integer value to convert
Returns:
- A 32-bit signed integer representation of the input value
Implementation:
Sources: mmd_uuunyaa_tools/utilities.py14-15
strict_hash(text: str) -> int
Creates a SHA-1 hash of a string and converts it to a 32-bit integer.
Parameters:
text: The string to hash
Returns:
- A 32-bit signed integer hash of the input string
Sources: mmd_uuunyaa_tools/utilities.py18-19
to_human_friendly_text(number: float) -> str
Formats a number with SI prefixes (k, M, G, T, P, E) to make it more readable.
Parameters:
number: The number to format
Returns:
- A string with the formatted number and appropriate SI prefix
Example:to_human_friendly_text(1500) returns "1.50 k"
Sources: mmd_uuunyaa_tools/utilities.py22-36
File System Functions
These functions handle file system operations, particularly path normalization.
sanitize_path_fragment(path_fragment: str) -> str
Sanitizes a string for use in file paths by removing illegal characters and other problematic elements.
Parameters:
path_fragment: The string to sanitize
Returns:
- The sanitized string safe for file system use
Implementation Details:The function removes:
- Illegal characters (/, ?, <, >, , :, *, |, ")
- Control characters
- Reserved names (".", "..")
- Windows reserved names (CON, PRN, AUX, NUL, etc.)
- Trailing dots and spaces
Sources: mmd_uuunyaa_tools/utilities.py43-65
Addon Integration Functions
These functions help integrate the addon with Blender and other required addons.
get_preferences()
Retrieves the addon preferences from Blender's context.
Returns:
- The addon preferences object
Sources: mmd_uuunyaa_tools/utilities.py39-40
is_mmd_tools_installed() -> bool
Checks if the MMD Tools addon is installed.
Returns:
Trueif MMD Tools is installed,Falseotherwise
Sources: mmd_uuunyaa_tools/utilities.py68-69
import_mmd_tools()
Imports the MMD Tools module or raises an error if not installed.
Returns:
- The imported MMD Tools module
Raises:
RuntimeErrorif MMD Tools is not installed correctly
Sources: mmd_uuunyaa_tools/utilities.py72-76
UI Helper Functions
These functions assist with creating user interface elements.
label_multiline(layout, text='', width=0)
Creates multiline labels in the Blender UI with automatic line wrapping.
Parameters:
layout: The Blender UI layout to add the labels totext: The text to displaywidth: Optional width parameter for calculating line wrapping threshold
Implementation Details:The function splits the text into lines and further splits each line if it exceeds the calculated threshold. Each segment is added as a separate label to the layout.
Sources: mmd_uuunyaa_tools/utilities.py79-89
Error Handling Functions
These functions and classes provide consistent error handling throughout the addon.
raise_installation_error(base_from)
Raises a standardized RuntimeError about incorrect installation.
Parameters:
base_from: The original exception to include as the cause
Raises:
RuntimeErrorwith a message about incorrect installation
Sources: mmd_uuunyaa_tools/utilities.py92-93
MessageException class
A custom exception class for errors with message content.
Inheritance:
- Inherits from the standard
Exceptionclass
Usage:
- Used for errors that need to include a descriptive message
Sources: mmd_uuunyaa_tools/utilities.py96-97
Usage Examples
The following table provides examples of how to use each utility function:
| Function | Example Usage |
|---|---|
to_int32 | value = to_int32(some_large_integer) |
strict_hash | hash_value = strict_hash("some string") |
to_human_friendly_text | formatted_value = to_human_friendly_text(1500) # Returns "1.50 k" |
sanitize_path_fragment | safe_name = sanitize_path_fragment("file/name?with:illegal*characters") |
get_preferences | prefs = get_preferences()some_setting = prefs.some_setting |
is_mmd_tools_installed | if is_mmd_tools_installed(): # Do something that requires MMD Tools |
import_mmd_tools | try: mmd_tools = import_mmd_tools() # Use mmd_toolsexcept RuntimeError as e: # Handle the error |
label_multiline | label_multiline(layout, "This is a long text that will be wrapped") |
raise_installation_error | try: # Do somethingexcept SomeException as e: raise_installation_error(e) |
MessageException | raise MessageException("Something went wrong") |
Sources: mmd_uuunyaa_tools/utilities.py
