get_fill_light_position_spherical
Retrieve the current fill light position in spherical coordinates relative to the camera. Use this to maintain accuracy when making relative lighting adjustments in 3D scenes.
Instructions
Get the current fill light position in camera-centric spherical coordinates. Query this before relative position changes (e.g., "rotate light 10 degrees") to ensure accuracy. For absolute changes, you may use recently queried state from context if no manual interactions occurred.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- server.js:1355-1403 (handler)The tool handler implementation for get_fill_light_position_spherical. This function retrieves the current fill light position in camera-centric spherical coordinates (azimuth, elevation, distance) from the browser state and returns it formatted with metadata including source and timestamp.mcpServer.registerTool( 'get_fill_light_position_spherical', { title: 'Get Fill Light Position (Spherical Coordinates)', description: 'Get the current fill light position in camera-centric spherical coordinates. ' + 'Query this before relative position changes (e.g., "rotate light 10 degrees") to ensure accuracy. ' + 'For absolute changes, you may use recently queried state from context if no manual interactions occurred.', inputSchema: {} }, async () => { const sessionId = getCurrentSessionId(); if (!sessionId) { return { content: [ { type: 'text', text: 'Error: No active session found.' } ], isError: true }; } try { const { state, metadata } = await getState(sessionId); const position = state.fillLight?.position || { azimuth: 0, elevation: 0, distance: 0 }; const positionText = `azimuth ${position.azimuth}°, elevation ${position.elevation}°, distance ${position.distance}`; return { content: [ { type: 'text', text: formatStateResponse(positionText, 'Fill light position', sessionId, metadata) } ] }; } catch (error) { return { content: [ { type: 'text', text: `Error retrieving fill light position: ${error.message}` } ], isError: true }; } } );
- server.js:1355-1363 (registration)Tool registration for get_fill_light_position_spherical. Registers the tool with MCP server including title, description, and empty inputSchema definition.mcpServer.registerTool( 'get_fill_light_position_spherical', { title: 'Get Fill Light Position (Spherical Coordinates)', description: 'Get the current fill light position in camera-centric spherical coordinates. ' + 'Query this before relative position changes (e.g., "rotate light 10 degrees") to ensure accuracy. ' + 'For absolute changes, you may use recently queried state from context if no manual interactions occurred.', inputSchema: {} },
- server.js:1057-1068 (schema)Azimuth schema definition used by fill light position tools. Accepts numbers (0-360) or direction names as strings, with validation against availableDirectionNames.const azimuthSchema = z.union([ z.number().min(0).max(360), z.string().refine( (val) => { const normalized = normalizeDirectionName(val); return normalized && directionToAzimuthMap.has(normalized); }, { message: `Must be a number (0-360) or a direction name. Available directions: ${availableDirectionNames}` } ) ]).describe(`Horizontal angle in degrees (0-360) or direction name (e.g., "north", "northwest", "NW"). 0° = camera forward (North), 90° = camera right (East), 180° = behind camera (South), 270° = camera left (West). Available directions: ${availableDirectionNames}`);
- server.js:284-316 (helper)Helper function getState that queries state from the browser (or uses cache if unavailable). Used by get_fill_light_position_spherical to retrieve current fill light position data.async function getState(sessionId) { let state; let source; let wasCached = false; // Always query browser for current state try { state = await queryStateFromBrowser(sessionId); source = 'fresh'; } catch (error) { // If query fails, fall back to cache if available (browser may be disconnected) const cached = sessionStateCache.get(sessionId); if (cached) { console.warn(`Browser query failed for session ${sessionId}, returning cached state: ${error.message}`); state = cached.state; source = 'cache'; wasCached = true; } else { // No cache available, throw error throw new Error(`Unable to retrieve state: ${error.message}. Browser may be disconnected.`); } } // Return state with metadata return { state, metadata: { source, wasCached, timestamp: new Date().toISOString() } }; }
- server.js:319-327 (helper)Helper function formatStateResponse that formats state query responses with metadata (timestamp, source, staleness warning). Used by get_fill_light_position_spherical to format the output.function formatStateResponse(value, propertyName, sessionId, metadata) { const timestamp = metadata.timestamp; const source = metadata.source; const stalenessWarning = metadata.wasCached ? ' (using cached state - browser may be disconnected)' : ''; return `${propertyName}: ${value} (queried at ${timestamp}, source: ${source}${stalenessWarning})`; }