NebulaPro v2.0 – Documentation
Professional EXR Nebula & Space Environment Manager for Blender
Introduction
NebulaPro v2.0 is a professional Blender add‑on designed for artists who need high‑quality, flexible space environments. Built around OpenEXR‑based nebula textures, it offers dual‑layer compositing, independent lighting controls, and a full suite of color and transformation tools – all directly in Blender’s World Properties.
Whether you are creating cinematic sci‑fi scenes, atmospheric backdrops, or stylized space art, NebulaPro gives you the power to craft stunning environments with ease.
Key Features at a Glance
Dual‑Layer System – Blend two distinct EXR nebulae with multiple blend modes.
Base Stars – An independent 8K star field layer with full color controls.
Illumination Modes – Choose between Additive (bright, energetic lighting) or Mix (balanced, atmospheric lighting).
Light Angle Offset – Rotate the lighting direction independently from the visible background.
Lock Lighting – Decouple a layer’s lighting contribution from its visual transforms.
Per‑Layer Power & Global Boost – Fine‑tune the highlight intensity for each layer and overall scene.
Downscaling – Reduce EXR resolution (Full, 4K, 2K, 1K) for better performance.
Favorites & Presets – Mark frequently used nebulae and save complete environment setups.
Performance Optimizations – Intelligent memory management, caching, and frame‑change updates.
Full Animation Support – All controls are keyframeable.
Version: 2.0.1
Blender Compatibility: 4.0 and later (including LTS versions)
Author: Kaleab Star
License: Python source code – GNU General Public License v3 or later; EXR assets and thumbnails – proprietary (see License section).
Installation
Download the NebulaPro v2.0 ZIP file (do not extract it).
Open Blender and go to Edit → Preferences → Add‑ons.
Click Install… and select the ZIP file.
Search for “NebulaPro” in the add‑ons list and enable it by checking the box.
Close the Preferences window. The add‑on is now installed.
Important: Ensure the exr/ and thumbnails/ folders are present in the add‑on’s installation directory (they are included in the ZIP). If missing, the add‑on may warn about unavailable nebulae.
Getting Started
Open the World Properties tab (globe icon) in Blender’s Properties Editor.
Locate the NebulaPro panel.
Check Enable NebulaPro to activate the environment.
Select a nebula from the Layer 1 thumbnail grid (use the Prev/Next buttons or click directly).
Adjust basic transformations (Rotation, Scale, Location, Mirror) to frame your environment.
Tweak Color & Tone (Hue, Saturation, Tint, Temperature, etc.) to match your scene.
Use Background Strength to control visible brightness and Lighting Strength to adjust how strongly the environment lights your objects.
Switch between Cycles and Eevee using the buttons in the panel for fast previews or final renders.
The add‑on automatically creates a custom world shader node group. All settings are saved with your Blender file.
Main Features & Settings
Enable / Disable & Engine Switching
Enable NebulaPro – Toggles the environment on/off. When disabled, the original world (if any) is restored.
Engine Buttons – Quickly switch between Cycles and Eevee. When using high‑resolution EXRs in Cycles, downscaling is recommended for better performance.
Layer 1 (Primary Nebula)
Nebula Selection – Choose from available EXRs via thumbnails. Use the Previous/Next buttons or Random Nebula for quick selection.
Downscale Layer 1 – Reduce resolution (Full, 4K, 2K, 1K) to improve performance. Recommended for Cycles on large scenes.
Transformations – Rotation, Scale, Location, Mirror Horizontal/Vertical.
Color Adjustments (collapsible) – Hue, Saturation, Value, Tint, Temperature, Brightness, Contrast, Gamma, and an RGB Curve for precise grading.
Lock Lighting – When enabled, the lighting contribution of Layer 1 remains fixed even if you rotate or scale the visible background. This decouples visual framing from light direction.
Layer 2 (Secondary Nebula)
Enable Layer 2 – Adds a second nebula for blending.
Second Nebula Selection – Similar to Layer 1, with its own thumbnails and random button.
Blend Amount – Controls the influence of Layer 2 (0 = only Layer 1, 1 = only Layer 2).
Blend Mode – Choose from Mix, Add, Screen, Overlay, Multiply.
Downscale Layer 2 – Resolution options, same as Layer 1.
Transformations & Adjustments – Identical to Layer 1, but applied to the secondary layer.
Lock Lighting – Independent lock for Layer 2.
Base Stars
Enable Base Stars – Activates a high‑quality 8K star field.
Strength – Overall visibility of the stars.
Rotation – Rotate the star field independently.
Color Adjustments – Full set of controls: Hue, Saturation, Value, Tint, Temperature, Brightness, Contrast, Gamma.
Illumination Modes
Additive Mode – Light from each layer adds directly on top of the other, creating brighter, more energetic lighting. Ideal for high‑contrast, emissive nebulae.
Mix Mode – Light contributions are blended in a balanced crossfade, offering more subtle, atmospheric illumination.
Strength Panel
Background Strength – Controls the visible brightness of the environment (background).
Lighting Strength – Controls how strongly the environment contributes to scene lighting.
Layer 1 Power – Multiplies the lighting contribution of Layer 1.
Layer 2 Power – Multiplies the lighting contribution of Layer 2 (if enabled).
Global Light Power – A master multiplier that boosts overall scene lighting from both layers.
Ambient Strength & Color – Adds a constant fill light to prevent shadows from being too dark.
Light Angle Offset
Light Angle Offset – Rotates the lighting direction independently from the visible background. This allows you to match the light direction to your scene’s key light without moving the environment.
Randomize – Applies a random rotation to the offset.
Reset – Returns the offset to zero.
Transformations & Locking
Each layer has its own Rotation, Scale, Location, Mirror controls.
Lock Lighting – For each layer, toggling this locks the lighting contribution to its current transformation. Useful when you want to keep consistent lighting while adjusting the visual placement of the nebula.
Favorites & Presets
Favorites – Mark nebulae as favorites (star icon next to the selection). The Show Favorites Only filter displays only your favorite items.
Presets – Save the entire environment configuration (including EXR selections, blend modes, colors, strengths, and transforms) as a JSON file. Load and delete presets directly from the panel.
Performance Tools
Downscaling – Each layer can be downscaled independently. Cached resized EXRs are stored in the system temp folder to avoid re‑processing.
Cleanup Unused Images – Removes orphaned EXR images from Blender’s memory, freeing up VRAM/RAM.
Frame‑Change Optimization – The node tree updates only when transformation values actually change, reducing unnecessary recalculations during animation playback.
Additional Buttons
Reset – Restores all settings to their defaults.
Switch to Cycles / Eevee – One‑click render engine switching.
Cleanup Unused Images – Manual memory cleanup.
UI Structure
The NebulaPro panel is organized into five tabs for a clean workflow:
Workflow Tips
Start in Eevee – Use Eevee for fast viewport feedback when adjusting transforms and colors.
Downscale for Performance – Set downscaling to 2K or 1K while iterating; switch to Full Resolution only for final renders.
Use Lock Lighting – Once you have the desired lighting direction, enable Lock Lighting on a layer to prevent accidental changes when framing the background.
Experiment with Light Angle Offset – If your scene’s key light doesn’t match the environment’s natural direction, use the offset to rotate lighting independently.
Combine Layer Powers for Highlights – Increase Layer 1 Power or Layer 2 Power to make the brightest parts of the EXR “pop” and create realistic glows on objects.
Save Presets – After achieving a look you like, save it as a preset for reuse in other projects.
Performance Considerations
EXR Resolution – Full‑size EXRs (8K+) require significant system memory (16GB+ RAM recommended). Downscaling reduces memory usage.
Eevee vs. Cycles – Eevee is faster for previews; Cycles provides physically accurate lighting but may be slower. Use downscaling and consider GPU rendering in Cycles.
Memory Cleanup – If you switch between many nebulae, occasionally use Cleanup Unused Images to free memory.
Caching – Downscaled images are cached in the system temp folder. If you need to clear the cache, you can manually delete files from that folder.
Troubleshooting
Limitations
NebulaPro does not modify scene geometry or replace physical sky/sun systems.
Performance depends on EXR resolution and available system memory.
The add‑on is designed for Blender 4.0 and later; earlier versions are not tested.
License & Credits
Copyright (c) 2026 Kaleab Star. All rights reserved.
Python source code (all .py files) is licensed under the GNU General Public License version 3 (GPL v3) or later. This means you are free to use, study, modify, and redistribute the code under the terms of the GPL.
EXR files and thumbnail images are proprietary assets. They are provided for use with NebulaPro only and may not be redistributed, resold, or used outside of the add‑on without written permission.
For full license details, refer to the LICENSE.txt file included with the add‑on or visit https://www.gnu.org/licenses/.
For support, feature requests, or bug reports, contact:
[email protected]
NebulaPro v2.0 – By Kaleab Star
kaleab
