Light Wrangler Add-on Installation and Configuration Guide

Installation Steps

1. Download: Acquire the .zip file provided with your purchase. Do not extract the archive.
2. Installation:
   • Open Blender.
   • Go to Edit > Preferences > Add-ons > Install.
   • Navigate to and select the downloaded .zip file.
3. Activation:
   • Find the add-on in the list.
   • Check the box next to its name to activate the add-on.

Configuration Settings

Access the settings for Light Wrangler through Edit > Preferences > Add-ons, then find and select "Light Wrangler".

Initial Light Settings

• Initial Light Distance: Defines the starting distance between the light and the object.
• Initial Light Power: Sets the starting power level of the light.
• Initial Light Temperature: Determines the initial color temperature of the light. Set to 0 for plain RGB emission.
• Initial Light Size: Establishes the starting size of the light source.
• Initial Light Spread: Sets the initial spread angle of the light.
• Initial Positioning Mode: Chooses between "Reflect" or "Direct" mode for initial light positioning.
• Orbit Sensitivity Setting: Fine-tune light orbit responsiveness with adjustable values between 0.1 and 2.0.

Advanced Settings

• Light Customization: Enables a panel for detailed light customization. Note: This feature is exclusive to the Cycles renderer.
• Smart Light Adjustments: Activates automatic calculation of light power based on its size and distance to the object.
• Show Viewport Hints: Toggles the display of textual hints in the viewport.
• Hide Viewport Overlays: Toggle to enable or disable viewport overlays hiding.
• Auto Light Visibility: Toggles light visibility with selection for streamlined workflow.
• Organize Lights: Automates new light arrangement into a 'Lights' collection and renames based on light mode.

Ground Level Settings

• Smart Ground Detection: Prevents the light from being positioned below ground level by automatically detecting the ground under the light.
• Use Manual Ground Level: Allows for the manual setting of a ground level, below which the light cannot be positioned.

Light Wrangler Add-on Usage Guide

Adding and Adjusting Lights

Adding a Light

• Right-click and navigate to Light Operations > Add Light.
• Use the F9 hotkey.

Real-Time Adjustments

• Power: Adjust with the Mouse Wheel or two-finger scroll on a touchpad.
• Size: Use Shift + Mouse Wheel or Shift + two-finger scroll on a touchpad.
• Proximity: Modify with Alt + Mouse Wheel or Alt + two-finger scroll on a touchpad to adjust the light's closeness to the object.
• Spread: Alter with Ctrl + Mouse Wheel or Ctrl + two-finger scroll on a touchpad.
• False Color Mode: Press the F key to toggle between the current view transform and False Color mode during light positioning.
• Light Direction Inversion: Press the I key to invert the light direction relative to the hit point.
• HDRI Rotation: Use Alt + Right Mouse Drag to rotate world HDRIs and dome objects directly in the viewport.

Toggle Light Positioning Modes

• In the active light placement mode, press 1, 2, or 3 to select Reflect, Orbit, or Direct modes, respectively.
• Alternatively, use the SPACE key to toggle through these modes.

Adjust Existing Lights

• Select the light, right-click and choose Light Operations > Adjust Light.
• Utilize the TAB hotkey or the Pie Menu (Ctrl+TAB).

Watch this video tutorial to understand why your lights might jump when you enter adjust mode and learn how to "fix" it.

Track to Target

• Right-click Light Operations and select "Track to Target".
• Choose to create a new empty for tracking or use an existing object. If multiple lights are selected, all will target the chosen point.

Light Visibility Controls

• Hide Current Light: Press H to toggle hiding the current light.
• Isolate Current Light: Press Shift + H to toggle isolating the current light.

Light Temperature

Cycle through light temperatures with the T key, switching the light from warm, to neutral, to cool.

Pause Automatic Positioning

Temporarily disable automatic positioning by pressing P. Press P again to resume.

Light Linking Control

• Press L to add the object under the mouse to the current light's linking collection.
• Press L again to exclude it, and press L a third time to remove it from the collection entirely.
• Use Shift+L to manage shadow linking with the same sequence of actions.

Light Customization (Cycles Renderer Exclusive)

Located in the light data tab, the light customization panel offers unique options for each light type:

• Area Light: Choose from default, scrim, HDRI, or gobo.
• Spot Light: Options include default and gobo.
• Point Light: Select between default and IES profiles.

Special Customizations

• Procedural Scrim: Transform an area light into a light scrim effect with adjustable feathering and tilt.
• HDRI Textures: Apply HDRI textures like Octabox, Parabolic Reflector, Umbrella, Fresnel, LED panel, etc.
• Gobos: Use gobos for dynamic shadows in your scene, with some options featuring animation.
• IES Profiles for Point Lights: Accurately replicate real-world lighting patterns with IES light profiles.
• Interactive Scrim Lights Preview: A new interactive preview in the customization panel for Scrim lights.
• Custom GOBO Textures: Option to add custom GOBO texture folders.

HDRI Scene Rendering

Located in the World tab, this feature allows you to render a 360° HDRI image of the current scene with a single click.

Light Wrangler Changelog

v2.4.0 - 12/16/2024

• Fix: Resolved "Convert to Plane" error in Gobo caused by missing shadow_method attribute.

v2.3.9 - 12/13/2024

• Auto Keying Improvements: Enhanced compatibility with Blender's Animation Preferences settings.

v2.3.8 - 12/11/2024

• HDRI Scene Rendering: Added support for emissive mesh objects. Including these objects increases render times.
• Blender Auto Keying: Light Wrangler operations now add changes to keyframes when Auto Keying is enabled.

v2.3.7 - 12/10/2024

• Initial Light Positioning States: Added an option to choose the initial light positioning state when entering Light Adjust Mode. Two states are now available:
  • Active: Light positioning is automatically activated upon entering Light Adjust Mode (default behavior).
  • Inactive: Disables light positioning upon entry, allowing only adjustments to light properties (e.g., size, power, distance, spread) without altering light position. To change the position, users can manually select a mode by pressing 1, 2, or 3.
• HDRI Rotation Scale: Added a visual scale when using Alt + right mouse drag to rotate the HDRI. The scale displays the exact HDRI rotation in degrees for more precise adjustments.

v2.3.6 - 12/05/2024

• Light Direction Inversion Shortcut: Added "I" key to invert light direction relative to the hit point.
• Viewport Text Hints Adjustment: Improved positioning to avoid overlap with the T-panel.

v2.3.5 - 12/05/2024

• Blender 4.3+ Compatibility: Fixed use_contact_shadows error.

v2.3.4 - 12/03/2024

• New Orbit Sensitivity Setting: Added for fine-tuning light orbit responsiveness with adjustable values between 0.1 and 2.0.
• Shift Key Modifier: Holding Shift reduces the orbit sensitivity to one-fifth of its default value for precise adjustments.

v2.3.3 - 12/03/2024

• False Color Mode Shortcut: Added shortcut (F key) to toggle between the current view transform and False Color mode during light positioning.
• Isolate Light Gizmo Adjustment: The light gizmo in the bottom right corner now shifts with the expanded and collapsed N-panel, ensuring it is no longer obstructed.

v2.3.2 - 12/03/2024

• Tweaked optimized light placement algorithms to improve performance in scenes with extremely high polygon counts, reducing memory usage and addressing crash reports.

v2.3.1 - 12/02/2024

• Fixed an issue introduced in v2.3.0 affecting light positioning on collection instances.
• Reverted optimized light placement algorithms from v2.3.0 due to identified bugs.

v2.3.0 - 12/02/2024

• Partial Compatibility with Blender 4.4.0 Alpha: Light placement functionality issues are now fully resolved. Note: Extension updates or remote installs are currently unsupported.
• Optimized Light Placement Algorithms: Improved performance for scenes with extremely high polygon counts to reduce memory usage and prevent crashes reported by some users.

v2.2.9 - 11/30/2024

• Partial Compatibility with Lens Sim Add-On: Support implemented with some limitations.
• Known Issue: Light positioning is not functional when Lens Sim camera uses auto-focusing.

v2.2.8 - 11/21/2024

• Bug Fix: Resolved an issue in Blender 4.3 (Eevee) causing a runtime error with the use_contact_shadow attribute for area lights. This fix addresses the traceback error and ensures proper functionality in affected scenes.

v2.2.7 - 11/07/2024

• Alt + Right Mouse Drag: Simplified rotation of world HDRIs and dome objects directly in the viewport.
• Light Visibility System: Improved manual visibility handling. Lights toggled manually remain in manual mode, while others sync with the selection state.
• ColorTemp Slider: Enhanced usability with integer mode for smoother drag adjustments, avoiding overly precise float values.

v2.2.5 - 11/05/2024

• Light Visibility System: Introduced intelligent detection for manual visibility changes. Manually toggled lights remain in manual mode, while other lights automatically sync with selection state.
• Color Temperature Slider Adjustment: Slider now operates in integer mode for smoother adjustments during drag operations, eliminating overly precise float values.

v2.2.4 - 10/17/2024

• Bug Fix: Resolved an issue where canceling adjustments (with Escape or right-click) would delete light/shadow linking collections from other lights using the same collection as the current light.
• Partial Fix: Partially resolved errors when working with collection instances scattered using geometry nodes.

v2.2.3 - 10/12/2024

• HDRI Conversion Bug Fix: Resolved issue with the convert to HDRI feature.
• Shift+Tab Fallback: If the TAB key is unavailable, the addon now uses Shift+Tab.

v2.2.2 - 10/11/2024

• Fixed bug in Light Isolation feature where emissive geometry states were not reverted properly.

v2.2.1 - 10/08/2024

• Major Bug Fix: Resolved issue where objects positioned between the viewer and target object, but clipped due to camera clipping, would obstruct light placement. Targeting objects now works correctly even with camera clipping, which is common in archviz scenes.

v2.2.0 - 10/01/2024

• Orbit Mode Snap: Hold CTRL to snap the light to the left, right, top, bottom, behind, or in front of the object while positioning in orbit mode.
• Clear Tracking: Easily remove light tracking to adjust positions in interactive mode.
• Bug Fixes and Stability Improvements: Minor fixes and performance enhancements for smoother workflow.

v2.1.9 - 09/15/2024

• Urgent Bug Fix: Addressed a critical failure in custom HDRI texture handling that could cause crashes or unpredictable behavior.

v2.1.8 - 09/15/2024

• Light Gizmo Positioning: Partial fix for unpredictable movements.

v2.1.7 - 09/14/2024

• Smart Light Adjustments: Now turned off by default.
• Text Hints Improvements:
  • Value metrics now align with user settings, and brackets are removed.
  • Values are rounded to take up less space and improve readability at a glance.
  • Text color adjusted and shadow added for better legibility on bright backgrounds.

v2.1.6 - 09/13/2024

• Viewport Hints Layout Improvement: Enhanced layout for better clarity.
• Trackpad Control Sensitivity: Calibrated to more reasonable values for smoother control.

v2.1.5 - 09/09/2024

• Fixed issue with loading user-defined image previews.
• Light/Shadow linking in Direct Mode: Fixed issue with L/Shift+L shortcut.

v2.1.4 - 08/31/2024

• Fixed an issue related to switching, entering, or exiting modes in certain scenarios.

v2.1.3 - 08/24/2024

• Stability Improvements: Fixed issues that could cause errors during light positioning cancellation.

v2.1.2 - 08/23/2024

• Critical Bug Fix: Resolved a major issue with the new hiding/isolation logic in active mode that affected functionality.

v2.1.1 - 08/22/2024

• Updated Viewport Text Hints: Selected mode is now highlighted, and power, size, distance, and spread text shortcut hints display their values. Hints are dynamically shown based on available space in the viewport.
• Toggle Light Visibility: In active mode, the 'H' key to hide light and 'Shift+H' to isolate light now function as toggles, no longer requiring the keys to be held down.
• Enhanced Light Isolation: In non-active mode, when a light is isolated using the Star button, you can now switch between isolating different lights by clicking them in the outliner.
• Bug Fix: Corrected an issue where the interactive scrim preview displayed the wrong color temperature.

v2.1.0 - 08/20/2024

• Light Linking Control: Introduced a new feature for managing light linking in scenes. In active mode, press 'L' to add the object under the mouse to the current light's linking collection. Press 'L' again to exclude it, and press 'L' a third time to remove it from the collection entirely. Use 'Shift+L' to manage shadow linking with the same sequence of actions.

v2.0.9 - 08/13/2024

• Fixed issue where the addon failed with objects having non-mesh outputs from Geometry Nodes.

v2.0.8 - 08/09/2024

• Fixed issue where changing the texture of one duplicated light would change it for all, affecting Gobo, IES, and HDRI textures. Duplicated lights now operate independently without any unintended synchronization.

v2.0.7 - 08/08/2024

• ColorTemp Setting: Set ColorTemp to 0 to enable plain RGB emission.
• Initial Light Temperature: Option to set Initial Light Temperature to 0 in addon settings for consistent RGB emission.

v2.0.6 - 07/30/2024

• Custom IES Profiles: Added option to set custom folders for IES profiles.

v2.0.5 - 07/25/2024

• Trackpad Scroll Support: Added functionality for trackpad scrolling.

v2.0.4 - 07/22/2024

• Isolate Light Function: Fixed attribute error.

v2.0.3 - 07/17/2024

• Bug Fix: Resolved error when placing light with 'Curve' object.

v2.0.2 - 07/17/2024

• Bug Fix: Resolved issue with light hiding/isolation not reverting after exiting light positioning mode.

v2.0.1 - 07/16/2024

• Orbit Mode Gizmo: Partial fix for unpredictable behaviors.

v2.0 - 07/15/2024

• Compatibility with Blender 4.2: Fully supports the latest Blender version.
• Improved Light Positioning Algorithm: Rewritten from scratch for better accuracy and predictability.
• Stability Enhancements: Numerous improvements for increased stability.
• Custom GOBO Textures: Option to add your own folders with custom GOBO textures in the settings.

v1.9.11 - 06/26/2024

• Orbit Mode Fix: Resolved issue where scrolling without moving the mouse would change the light angle unexpectedly.

v1.9.9.2 - 05/25/2024

• Shortcut Customization: Added option to customize shortcuts via addon preferences.

v1.9.9.1 - 05/20/2024

• Critical Bug Fix: Resolved major issue with Point Light IES customization mode from versions 1.9.9 and 1.9.8.

v1.9.8 - 05/07/2024

• Convert to Plane Button: Added in Gobo Customization Mode for converting gobo area lights into planes with stencil textures, enhancing integration with main world lights.
• Enhanced Gobo Controls: New 'Invert Gobo' toggle and rotation slider improve flexibility in gobo effect management.
• New Gobo Textures: Introduction of additional gobo textures, expanding creative lighting options.
• Convert to HDR: Replaces 'Render Scrim to EXR', automatically integrating HDR images into node emission setups.
• HDRI Scene Rendering: New option in the World tab to render a 360° HDRI image of the current scene with a single click.

v1.9.6 - 04/04/2024

• Organize Light Feature Update: Reverted to beta status and disabled by default.

v1.9.3 - 03/20/2024

• Critical 'Organize Lights' Bug Fix: Addressed a major usability issue from v1.9.2. Updating is mandatory for all v1.9.2 users.

v1.9.2 - 03/19/2024

• Custom HDRI Textures: Introducing the ability to add personal HDRI texture folders for enhanced lighting customization.
• Auto Light Visibility: Improved feature reintroduction - toggles light visibility with selection for streamlined workflow.
• Organize Lights: Automates new light arrangement into a 'Lights' collection and renames based on light mode for project neatness.
• Orbit Mode Enhancement: Mouse cursor now seamlessly teleports across the screen edges in Orbit mode, ensuring uninterrupted navigation.
• Interactive Scrim Lights Preview: A new interactive preview in the customization panel for Scrim lights, enhancing user experience.
• Bug Fixes: Addressed orthographic mode light positioning issues, fixed Orbit mode navigation problems, and eliminated multiple minor bugs for increased stability.

v1.8.5 - 02/25/2024

• Logical HDRI Image Sorting: HDRI images now arranged in a more intuitive order.

v1.8.4 - 02/24/2024

• Gobo Texture Application Fix: Corrected issue with Gobo texture application in older Blender 3 versions.
• Orbit Positioning Mode Enhancement: Improved behavior for retrieving orbit positioning mode.
• New HDRI Light Textures: Addition of several new HDRI light textures.

v1.8.3 - 02/24/2024

• Fixed a bug that prevented light gizmos from being retained across Blender sessions.

v1.8.2 - 02/23/2024

• Bug Fix: Issue with incorrect last adjustment mode retrieval corrected.

v1.8.1 - 02/22/2024

• Fixed a critical bug causing unexpected resets in light-to-object proximity.

v1.8.0-Beta - 02/22/2024

• New Visual Representations for Positioning Modes: Redesigned gizmos for Reflect, Orbit, and Direct modes for intuitive use and better aesthetics.
• Enhanced User Experience: Press 1, 2, or 3 for instant activation of Reflect, Orbit, and Direct modes.
• Quick Adjust Feature: Allows temporary Light Adjusting mode with a simple left mouse click (and drag) on any gizmo for swift light manipulation.

v1.7.8 - 02/18/2024

• Hide Viewport Overlays: Automatically hides overlays in light adjusting mode for a clearer view, toggleable in settings.
• Minor Improvements: Enhanced light auto-positioning algorithm for improved performance.

v1.7.6 - 02/15/2024

• Orthographic Mode Fix: Temporary solution for issues in orthographic mode.
• Viewport Text Hints: Option to disable viewport text hints added.

v1.7.5 - 02/13/2024

• Improved Positioning Mode Switching: Instant updates when switching modes.
• Renamed Positioning Modes: Reflect Mode and Direct Mode for clarity.
• Default Initial Positioning Mode: Option to set default mode in settings.
• Adjust Light Shortcut: Changed to TAB key from F10.

v1.6.9 - 12/03/2023 (Testing Release)

• Positioning Modes: Buttons 1, 2, 3 for mode change.
• Spacebar Functionality: Switch modes with the Spacebar.
• Adjust Light (F10) Enhancement: Remembers last used mode.

v1.6.1 - 11/30/2023

• New Positioning Mode - Normal: Perpendicular light positioning.
• Spacebar to switch positioning modes.

v1.5.9 - 11/29/2023

• Bug Fixes: General improvements for smoother experience.
• New Animated Vegetation Gobos: Introduction of 14 beta gobos.

v1.5.6 - 11/28/2023

• Bug Fixes: Several issues addressed.
• Performance Improvements: Enhancements for smoother performance.

v1.5.4 - 11/26/2023

• Gobo Functionality Improvements: Bug fixes and enhancements.
• Increased Stability: Under-the-hood improvements.

v1.5.1 - 11/24/2023

• Critical Performance Bug Fix: Important update for optimal performance.

v1.5.0 - 11/23/2023 (Early Access)

• Light Customizations: New feature in developmental stages.
• Animated GoBos: Introduction of a basic form of animated gobos.

v1.4.4 - 11/19/2023

• Auto Light Visibility Toggle: Enhanced control over visibility.
• Manual Ground Level Setting: Flexibility in ground-level adjustments.
• Duplicate Light Option: Quick light copying and adjustment.
• Improved Preferences Access: Direct access for easier customization.

v1.3

• Custom Emission Node Improvement: Enhanced control and feathering.
• Early Access to New Light Types: Parabolic and octabox lights.
• UI Enhancements: Smoother light mode switching and texture use.

v1.1.0

• Quick Light Constraining: Simplified light target setup.

v1.0.8 - 11/19/2023

• Temporary Light Hide Feature: 'H' key to temporarily hide lights.