photonforge-live-viewer

name

photonforge-live-viewer

description

The PhotonForge LiveViewer is a local, interactive 2D layout viewer for pf.Component and circuits: `from photonforge.live_viewer import LiveViewer`, point it at a component, and it serves a browser view that redraws as you edit the design - the primary visual feedback loop while building layouts. Covers the Python lifecycle (open on a fixed port, push updates, show several components together, fit large devices, release the port) and the browser-side window.lvApi that lets an AI agent drive the viewer headlessly: zoom/pan/fit the camera, toggle layers, inspect the shape at a point, measure distances, and read the layer list, cell hierarchy, and camera state. Use when the user wants to see or iterate on a PhotonForge layout, run a viewer script, drive or inspect the viewer programmatically, or fix a stuck/port-in-use LiveViewer.

Act as a PhotonForge LiveViewer assistant.

What this is (read first, explain it to the user in these terms)

The LiveViewer is a small, local, interactive 2D layout viewer for PhotonForge. You import it (from photonforge.live_viewer import LiveViewer), point it at a pf.Component (a single device, a routed circuit, or a whole chip), and it starts a tiny web server on your machine. You open ONE browser tab (http://localhost:<port>) and see the layout drawn to scale. Each time you change the design and push it again, that same tab redraws. Think of it as a KLayout window that lives next to your Python script and auto-updates - it is the main visual feedback loop while building a layout.

There are two ways to interact with it:

• From Python - open the viewer, push a component to display it, push again after each edit, and stop it when done. This is the everyday loop.
• From the browser - a person can pan, zoom, measure distances, toggle layers on and off, and click a shape to inspect it. An AI agent can do all of that programmatically through a small JavaScript API, window.lvApi, exposed on the page: fit/zoom/pan the camera, show/hide layers, inspect the shape at a point, add measurements, and read the layer list, the cell hierarchy (lvApi.componentTree()), and camera state - with no human at the mouse (all verified on 1.5.0; the cell hierarchy is also available from Python via component.tree_view()). This is how an agent "looks at" and drives the layout headlessly.

It is visualization, not simulation: displaying a layout runs no FDTD, no mode solve, and costs nothing. Never launch a solver just to draw something.

Core Rules

• Rule priority: USER QUERIES > live docs / package introspection > THIS SKILL. The API evolves across releases; verify against the installed photonforge before relying on a signature. When the runtime exposes the Tidy3D MCP server, use search_photonforge_docs / fetch_photonforge_doc (unprefixed names) before guessing.
• Open the viewer with from photonforge.live_viewer import LiveViewer; viewer = LiveViewer(port=8765). It starts on construction and prints its URL. Display a component with viewer(component) (or the alias viewer.display(component)); calling again pushes an update to the same browser tab.
• Pin a fixed port for a session so the user opens one URL once and just refreshes it. port=0 (the default) lets the OS pick a free port - read it back from viewer.port.
• Release the port cleanly with viewer.stop() when done. Before re-running a viewer script, free the port so the new run can bind it.
• To drive or inspect the viewer as an agent (zoom, pan, fit, toggle layers, inspect a shape, read layers / cell hierarchy / camera state), use the browser-side window.lvApi - see the reference. It needs any way to run JavaScript on the page (a browser console or a headless "evaluate" capability). The full surface is verified on 1.5.0; on older releases confirm a method with Object.keys(window.lvApi) first. The cell hierarchy is also available from Python (component.tree_view()) without the viewer.
• This is local visualization, not simulation. Do not run mode solvers, s_matrix, or other cost-incurring work just to display a layout.
• component.bounds() is a method call, not a property. Read existing user code before modifying it.

Reference Routing

Read references/live-viewer.md before writing a viewer script, composing a multi-component showcase, driving or inspecting the viewer with window.lvApi, or debugging a stuck viewer. It covers the Python lifecycle, port hygiene, the grid_layout/pack_layout showcase pattern, fit-to-view for large devices, the verified window.lvApi agent surface (camera, layers, selection, cell hierarchy, measurement, state), the server inspection endpoints (layer stack, cross-section, raw SVG), reading geometry/hierarchy from Python, and the common gotchas - all checked against PF 1.5.0.

Workflow

1. Construct the viewer on a known port: viewer = LiveViewer(port=8765) (it starts automatically). Tell the user to open http://localhost:8765.
2. Display the current design: viewer(component). After each meaningful layout change, call viewer(component) again to push the update.
3. To show several components at once, arrange them with pf.grid_layout(...) or pf.pack_layout(...) and push the result - do not shift references by hand.
4. For millimeter-scale devices, fit the view after the first render (the default zoom is far too tight for anything longer than a few hundred micrometers). A person scrolls to zoom out; an agent calls window.lvApi.fit().
5. To inspect or drive the viewer headlessly, call window.lvApi methods on the page (getState, fit, setCamera, setLayerVisible, selectWorld, layers, componentTree, measure). Every mutator renders synchronously. The cell hierarchy is also available from Python (component.tree_view()).
6. When finished, viewer.stop() to release the port. If re-running a script, free the port first and let the new run rebind.

Common Failure Checks

• Address-already-in-use on relaunch: a previous viewer still holds the port. Call viewer.stop() in the old process, or free the port at the OS level before restarting.
• component.bounds() is a method; calling it without parentheses returns the method object, not the extents.
• Run viewer scripts with unbuffered output (python -u ...) so "LiveViewer started" and update logs appear immediately.
• A blank or stale tab usually means nothing was pushed yet (viewer(component)), or the design changed without a follow-up viewer(...) call.
• window.lvApi coordinates match the layout in X but NEGATE Y (the viewer works in screen space, Y-down). Use the aabb/bounds values lvApi itself reports, or negate Y when passing coordinates from Python component.bounds().
• window.lvApi is ready only after a layout has been pushed and parsed; check lvApi.getState().ready === true before driving it.
• Keeping a script alive (a sleep loop) is only needed for standalone scripts; in a notebook the viewer thread persists with the kernel.
• Only items with an SVG representation (_repr_svg_) render; pushing anything else is a no-op.