What's the mood?
├── Studio / commercial → Three-point lighting (key+fill+rim) + HDRI fill 0.3
├── Outdoor / sunlit → Sun + HDRI sky environment
├── Indoor cinematic → Sun through window + HDRI low + practicals (lamps as Point)
├── Dramatic / noir → Single Spot at high angle, no fill
├── Stylized / cartoon → Three-point with high contrast + saturated key color
└── Unsure → Three-point with HDRI grounding (works for 90% of cases)

from mathutils import Vector

def aim_at(light_obj, target):
    """Aim a light at a world-space target.
    target may be a Vector or a tuple/list (x, y, z) or a Blender object.
    """
    target_pos = Vector(target.location) if hasattr(target, 'location') else Vector(target)
    direction = (target_pos - light_obj.location).normalized()
    light_obj.rotation_euler = direction.to_track_quat('-Z', 'Y').to_euler()

from mathutils import Vector

def compute_scene_bbox_center(meshes):
    """Average bbox center over a list of mesh objects (world space)."""
    import bpy
    deps = bpy.context.evaluated_depsgraph_get()
    all_verts = []
    for o in meshes:
        eval_obj = o.evaluated_get(deps)
        em = eval_obj.to_mesh()
        for v in em.vertices:
            all_verts.append(o.matrix_world @ v.co)
        eval_obj.to_mesh_clear()
    xs = [v.x for v in all_verts]
    ys = [v.y for v in all_verts]
    zs = [v.z for v in all_verts]
    center = Vector(((min(xs)+max(xs))/2, (min(ys)+max(ys))/2, (min(zs)+max(zs))/2))
    extent = max(max(xs)-min(xs), max(ys)-min(ys), max(zs)-min(zs))
    return center, extent

import bpy, math
from mathutils import Vector

def aim_at(light_obj, target):
    target_pos = Vector(target.location) if hasattr(target, 'location') else Vector(target)
    direction = (target_pos - light_obj.location).normalized()
    light_obj.rotation_euler = direction.to_track_quat('-Z', 'Y').to_euler()

def apply_three_point(subject_class='metal'):
    """Configure 3-point lighting with subject-class-aware ratios.

    subject_class: 'metal' | 'glass' | 'wood' | 'fabric' | 'skin' | 'product' | 'metal' (default)
    """
    profiles = {
        'metal':   dict(ratio=(4.0, 1.0, 2.0), key_color=(1.0, 0.95, 0.85), fill_color=(0.85, 0.9, 1.0), rim_color=(0.7, 0.85, 1.0)),
        'glass':   dict(ratio=(3.0, 1.0, 1.2), key_color=(1.0, 0.98, 0.95), fill_color=(0.95, 0.95, 1.0), rim_color=(0.95, 0.95, 1.0)),
        'wood':    dict(ratio=(4.0, 1.0, 1.5), key_color=(1.0, 0.92, 0.78), fill_color=(0.95, 0.95, 1.0), rim_color=(0.85, 0.92, 1.0)),
        'fabric':  dict(ratio=(3.0, 1.0, 0.5), key_color=(1.0, 0.97, 0.92), fill_color=(0.92, 0.95, 1.0), rim_color=(0.95, 0.95, 1.0)),
        'skin':    dict(ratio=(4.0, 1.0, 1.0), key_color=(1.0, 0.93, 0.82), fill_color=(0.95, 0.96, 1.0), rim_color=(0.92, 0.92, 1.0)),
        'product': dict(ratio=(5.0, 1.0, 1.5), key_color=(1.0, 0.98, 0.95), fill_color=(0.98, 0.98, 1.0), rim_color=(0.98, 0.98, 1.0)),
    }
    p = profiles.get(subject_class, profiles['metal'])

    # Compute scene bbox
    subject_meshes = [o for o in bpy.data.objects if o.type == 'MESH' and o.name.startswith('GEO-')]
    deps = bpy.context.evaluated_depsgraph_get()
    all_verts = []
    for o in subject_meshes:
        eo = o.evaluated_get(deps); em = eo.to_mesh()
        for v in em.vertices: all_verts.append(o.matrix_world @ v.co)
        eo.to_mesh_clear()
    xs = [v.x for v in all_verts]; ys = [v.y for v in all_verts]; zs = [v.z for v in all_verts]
    center = Vector(((min(xs)+max(xs))/2, (min(ys)+max(ys))/2, (min(zs)+max(zs))/2))
    biggest = max(max(zs)-min(zs), max(xs)-min(xs))
    light_dist = max(biggest * 1.5, 1.0)

    # Energy scales with distance²
    base_energy = 100 * (light_dist / 1.5) ** 2
    key_e, fill_e, rim_e = (base_energy * r for r in p['ratio'])

    # Remove existing lights
    for o in list(bpy.data.objects):
        if o.type == 'LIGHT' and (o.name.startswith('LGT-key') or o.name.startswith('LGT-fill') or o.name.startswith('LGT-rim')):
            bpy.data.objects.remove(o, do_unlink=True)

    # KEY (warm, front-right above)
    key = bpy.data.objects.new('LGT-key', bpy.data.lights.new('LGT-key', type='AREA'))
    key.data.energy = key_e; key.data.size = 0.5; key.data.color = p['key_color']
    bpy.context.collection.objects.link(key)
    key.location = (center.x + light_dist*0.7, center.y - light_dist*0.7, center.z + light_dist*0.5)
    aim_at(key, center)

    # FILL (cool, opposite, weaker)
    fill = bpy.data.objects.new('LGT-fill', bpy.data.lights.new('LGT-fill', type='AREA'))
    fill.data.energy = fill_e; fill.data.size = 1.0; fill.data.color = p['fill_color']
    bpy.context.collection.objects.link(fill)
    fill.location = (center.x - light_dist*0.7, center.y - light_dist*0.5, center.z + light_dist*0.3)
    aim_at(fill, center)

    # RIM
    rim_type = 'AREA' if subject_class == 'glass' else 'SPOT'
    rim = bpy.data.objects.new('LGT-rim', bpy.data.lights.new('LGT-rim', type=rim_type))
    rim.data.energy = rim_e; rim.data.color = p['rim_color']
    if rim_type == 'AREA':
        rim.data.size = 1.5   # larger soft-source for glass
    else:
        rim.data.spot_size = math.radians(50)
    bpy.context.collection.objects.link(rim)
    rim.location = (center.x, center.y + light_dist, center.z + light_dist*0.5)
    aim_at(rim, center)

    print(f"lighting:{subject_class} key:fill:rim={p['ratio']} dist={light_dist:.2f}m")

undefined

import bpy, math
from mathutils import Vector

def aim_at(light_obj, target):
    target_pos = Vector(target.location) if hasattr(target, 'location') else Vector(target)
    direction = (target_pos - light_obj.location).normalized()
    light_obj.rotation_euler = direction.to_track_quat('-Z', 'Y').to_euler()

undefined

import bpy
from mathutils import Vector

def aim_at(light_obj, target):
    target_pos = Vector(target.location) if hasattr(target, 'location') else Vector(target)
    direction = (target_pos - light_obj.location).normalized()
    light_obj.rotation_euler = direction.to_track_quat('-Z', 'Y').to_euler()

The practical light's emission shader (mesh-emissive bulb / candle flame / etc.) handles the rest. Scene appears like real photography of an illuminated subject — dark surroundings, warm pool of light from the practical, subject silhouette gently filled.

**Validation proof**: see `text-to-blender/assets/v1.1.0-validation/desk_lamp_emission.webp` for what this setup produces (desk lamp with visible bulb glow, warm light pool on desk surface, lamp body visible against the dark scene).

import bpy, math

**Standard ratios**:
- High-key (commercial): Key:Fill = 2:1
- Medium (portrait): 4:1
- Low-key (dramatic): 8:1+
- Rim: 50–100% of key

import bpy

world = bpy.context.scene.world
world.use_nodes = True
nodes = world.node_tree.nodes
links = world.node_tree.links

**Pro source**: free HDRIs at [polyhaven.com/hdris](https://polyhaven.com/hdris) (CC0).

import bpy, math

sun_data = bpy.data.lights.new('LGT-sun', type='SUN')
sun_data.energy = 5.0
sun_data.color = (1.0, 0.95, 0.8)  # golden hour
sun_data.angle = math.radians(0.5)  # realistic sun size; bigger = softer
sun = bpy.data.objects.new('LGT-sun', sun_data)
bpy.context.collection.objects.link(sun)
sun.location = (0, 0, 10)
sun.rotation_euler = (math.radians(45), math.radians(15), 0)
print('lighting:outdoor_sun')

import bpy, math

undefined

import bpy, math

spot_data = bpy.data.lights.new('LGT-drama', type='SPOT')
spot_data.energy = 800
spot_data.spot_size = math.radians(30)
spot_data.spot_blend = 0.3
spot_data.color = (1.0, 0.95, 0.85)
spot = bpy.data.objects.new('LGT-drama', spot_data)
bpy.context.collection.objects.link(spot)
spot.location = (2, -2, 6)
spot.rotation_euler = (math.radians(60), 0, 0)
print('lighting:dramatic')

import bpy, math

light_data = bpy.data.lights['LGT-key']

undefined