IntensityView Command API

Automate the running IntensityView desktop application with string commands over a local HTTP connection. The 38 commands documented here are the actions registered in this source revision; this is not a headless calculation service or a general REST resource API.

Read the complete agent reference, or download the standalone Markdown reference. The download contains the transport contract and all commands without requiring an agent to follow individual pages.

Connection and Execution

Start the desktop application with a valid license and keep its UI responsive. The server listens on IPv4 loopback only. Its default port is 4243; the examples use an explicitly selected 4757:

EWIntensityView.exe --commandserver=4757

Close an existing instance before changing the startup port. Check the application console for the listening address; another process can already occupy the port. Alternatively, use StartCommandServer 4757 in the local console when no listener is running. An already running server is not moved to a new port by that action.

Send one UTF-8, plain-text command per HTTP request:

POST /command HTTP/1.1
Host: 127.0.0.1:4757
Content-Type: text/plain; charset=utf-8

GetParameter flux 12

The body is not JSON, a URL query or a multi-line script. Commands run through the application's action/view-model system. UI dialogs, license checks and lengthy calculations can delay a response. OpenFile performs background work; its HTTP response is completed after loading finishes.

Command Grammar

• Command names are case-sensitive. Use the exact names in this reference.
• <name> is a required placeholder; brackets indicate optional arguments. Do not transmit the brackets or angle brackets.
• Separate tokens with spaces. Separators / and -> must be separate tokens.
• Use a decimal point and finite numeric values, never localized decimal commas, NaN or infinity.
• Double quotes group whitespace in paths and text; the tokenizer strips the quotes and preserves backslashes. Embedded quotes are not escaped, and empty quoted tokens are discarded. Always balance quotes.
• A filename such as "D:\Photometry\Sample lamp.ies" is one token. In a programming language, apply that language's string-literal escaping separately.
• Explicit target IDs are required by the commands that take IDs. An omitted ID does not mean "use the UI selection."

Model IDs

There are two different ID domains: parent LuminaireModel IDs and emitter IntensityModel IDs. They are not interchangeable, even if their numeric values happen to coincide.

OpenFile returns emitter IDs in groups, one group per requested file:

OK <number-of-emitters-in-file-1> <emitterId...> <number-in-file-2> <emitterId...>

For example, OK 2 12 13 1 20 represents two emitters from the first file and one from the second. A failed file can contribute a zero count when other files succeed. If all files fail, expect an error.

Most photometry editing and query commands take emitter IDs. RemoveLid, DuplicateLuminaire and ConfigureLuminaire take parent IDs; MoveMesh and SetGeometry explicitly distinguish the two. The loading console records parent IDs. This API has no general ID-enumeration endpoint: do not invent one or infer parent IDs from returned emitter IDs. Treat IDs as session-local and recheck targets after structural edits.

Responses and Safety

HTTP success is not application success. Inspect the response body for ERROR or CANCEL and validate its command-specific format. Queries often return bare values; modifications can return OK, descriptive text or an empty body. Some commands log skipped targets or failed saves while still returning OK. Check affected data or files as well as the console.

Send requests sequentially and await completion. A client timeout does not cancel an action; check the session before retrying, particularly after a load, duplicate or save. Multi-target commands are not guaranteed atomic. Undo and Redo share the application's history with UI operations and are not per-client transactions.

The endpoint has no authentication or TLS. Keep it on loopback, do not expose it through a proxy or port forwarding, and accept commands only from trusted local automation. Commands have the application's file-access privileges. Preserve originals, choose explicit output paths and obtain approval before destructive operations in an agent workflow.

Do not send StopCommandServer through the HTTP connection it must stop; use the local console. SetPhotometryUnit is currently a no-op at the mesh setter, and Combine does not remove its created output on undo. These limitations are documented on their command pages.

VBA

This synchronous helper uses MSXML2.ServerXMLHTTP.6.0, available through late binding on Windows. Put it in a standard VBA module. It checks transport status and explicit application errors without adding an arbitrary wait between requests.

Option Explicit

Public Function SendIntensityCommand(ByVal command As String) As String
    Dim http As Object
    Dim reply As String
    If Len(Trim$(command)) = 0 Then
        Err.Raise vbObjectError + 1000, , "Empty command."
    End If

    Set http = CreateObject("MSXML2.ServerXMLHTTP.6.0")
    http.setTimeouts 5000, 5000, 30000, 120000
    http.Open "POST", "http://127.0.0.1:4757/command", False
    http.setRequestHeader "Content-Type", "text/plain; charset=utf-8"
    http.Send command

    If http.Status <> 200 Then
        Err.Raise vbObjectError + 1001, , "HTTP " & CStr(http.Status)
    End If
    reply = Trim$(http.responseText)
    If Left$(reply, 5) = "ERROR" Or Left$(reply, 6) = "CANCEL" Then
        Err.Raise vbObjectError + 1002, , reply
    End If
    SendIntensityCommand = reply
End Function

Public Sub ReadSampleFlux()
    Dim fields() As String
    Dim reply As String
    Dim count As Long
    reply = SendIntensityCommand("OpenFile ""D:\Photometry\sample.ies""")
    fields = Split(reply, " ")
    If UBound(fields) < 2 Then Err.Raise vbObjectError + 1003, , reply
    If fields(0) <> "OK" Then Err.Raise vbObjectError + 1003, , reply
    count = CLng(fields(1))
    If count < 1 Or UBound(fields) <> count + 1 Then
        Err.Raise vbObjectError + 1003, , "Unexpected OpenFile response."
    End If
    Debug.Print SendIntensityCommand("GetParameter flux " & CLng(fields(2)))
End Sub

Python

This example uses only the Python standard library. It parses the response for one requested file and queries the first returned emitter. Network errors and timeouts propagate to the caller; do not automatically replay the command.

import urllib.request

ENDPOINT = "http://127.0.0.1:4757/command"

def send_command(command: str) -> str:
    if not command.strip():
        raise ValueError("Empty command")
    request = urllib.request.Request(
        ENDPOINT,
        data=command.encode("utf-8"),
        headers={"Content-Type": "text/plain; charset=utf-8"},
        method="POST",
    )
    with urllib.request.urlopen(request, timeout=120) as response:
        if response.status != 200:
            raise RuntimeError(f"HTTP {response.status}")
        reply = response.read().decode("utf-8").strip()
    if reply.startswith(("ERROR", "CANCEL")):
        raise RuntimeError(reply)
    return reply

def open_one_file(path: str) -> list[int]:
    if not path or '"' in path or "\n" in path or "\r" in path:
        raise ValueError("Path cannot be empty or contain quotes/newlines")
    fields = send_command(f'OpenFile "{path}"').split()
    if len(fields) < 3 or fields[0] != "OK":
        raise RuntimeError(f"Unexpected OpenFile response: {fields}")
    count = int(fields[1])
    ids = [int(value) for value in fields[2:]]
    if count < 1 or len(ids) != count or any(value < 0 for value in ids):
        raise RuntimeError(f"Invalid emitter list: {fields}")
    return ids

emitter_ids = open_one_file(r"D:\Photometry\sample.ies")
print(send_command(f"GetParameter flux {emitter_ids[0]}"))

C#

The following console program uses HttpClient and awaits each request. Reuse the client instead of constructing one per command. It requires a C# compiler supporting an async Main method.

using System;
using System.Globalization;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

internal static class Program
{
    private static readonly HttpClient Client = new HttpClient
    {
        Timeout = TimeSpan.FromMinutes(2)
    };

    private static async Task<string> SendCommandAsync(string command)
    {
        if (string.IsNullOrWhiteSpace(command))
            throw new ArgumentException("Empty command", nameof(command));
        using (var content = new StringContent(command, Encoding.UTF8, "text/plain"))
        using (var response = await Client.PostAsync(
            "http://127.0.0.1:4757/command", content))
        {
            response.EnsureSuccessStatusCode();
            string reply = (await response.Content.ReadAsStringAsync()).Trim();
            if (reply.StartsWith("ERROR", StringComparison.Ordinal) ||
                reply.StartsWith("CANCEL", StringComparison.Ordinal))
                throw new InvalidOperationException(reply);
            return reply;
        }
    }

    private static async Task Main()
    {
        string reply = await SendCommandAsync(
            "OpenFile \"D:\\Photometry\\sample.ies\"");
        string[] fields = reply.Split(
            new[] { ' ', '\r', '\n', '\t' }, StringSplitOptions.RemoveEmptyEntries);
        if (fields.Length < 3 || fields[0] != "OK" ||
            !int.TryParse(fields[1], out int count) ||
            count < 1 || count != fields.Length - 2)
            throw new InvalidOperationException("Unexpected OpenFile response: " + reply);

        int firstId = -1;
        for (int i = 2; i < fields.Length; ++i)
        {
            if (!int.TryParse(fields[i], out int id) || id < 0)
                throw new InvalidOperationException("Invalid emitter ID: " + fields[i]);
            if (i == 2) firstId = id;
        }

        Console.WriteLine(await SendCommandAsync(
            "GetParameter flux " + firstId.ToString(CultureInfo.InvariantCulture)));
    }
}

All three examples require replacing the sample path with an existing file. They intentionally query data without modifying the imported distribution. Use a new destination path and verify the file when adding SaveFile to a workflow.

Command Reference

File Input and Output

• OpenFile: Open one or more photometric files and add their luminaires to the session.
• SaveFile: Save an emitter distribution to a photometric file.
• RemoveLid: Remove one or more parent luminaires from the session.

Queries

• GetParameter: Read calculated or descriptive parameters of intensity models.
• GetProperty: Read a fixed named property from intensity models.
• GetPropertyField: Read a metadata field by its internal field name.

Properties and Flux

• SetProperty: Set a typed metadata field on one or more intensity models.
• SetLuminousFlux: Rescale the intensity distribution to a specified total luminous flux.
• SetLampFlux: Set stored lamp luminous flux.
• SetLampNumber: Set lamp count for the selected explicit targets.
• SetInputPower: Set the input power metadata.
• SetEmitterLOR: Rescale emitter output using a light-output ratio.
• SetPhotometryUnit: Request a photometry-unit change through the registered action.

Photometric Transforms

• SetSymmetryData: Apply a symmetry setting to intensity data.
• SetResolution: Resample intensity data into a specified photometry grid.
• RotateEuler: Rotate the intensity distribution using three angular parameters.
• RotateQuaternion: Rotate intensity data about a Cartesian axis.
• Scale: Stretch or compress the angular distribution along Cartesian X and Y.
• AutoAlignPhotometry: Search for an orientation aligned to a requested symmetry.
• Smoothen: Smooth samples along planar slices, conic slices or both.

Geometry

• SetGeometry: Replace luminaire or emitter geometry with a parametric primitive.

Luminaire and Channel Management

• ConfigureLuminaire: Rename a parent luminaire and set channel contribution percentages.
• DuplicateLuminaire: Duplicate one or more parent luminaires and their documents.
• MoveMesh: Move an emitter channel into another luminaire.
• RemoveMesh: Pop out or remove an emitter channel.
• Combine: Create a new luminaire by combining weighted intensity distributions.

Map Modification

• PaintBrush: Paint intensity or colour around angular map coordinates.
• FillSelection: Fill an angular selection with intensity or colour.
• ScaleAdd: Add to or multiply intensity within an angular selection.
• CloneTool: Clone angular-map samples using a source offset.
• ApplyTransform: Warp an intensity map using control-point displacements.

Roadway Scenarios

• LoadRoadwayScenarioFile: Load saved roadway scenarios into the current scenario collection.
• SaveRoadwayScenarioFile: Write a named roadway scenario to disk.

View

• SetCoordinateSystem: Change the coordinate system used to display photometric data.

Session and History

• Undo: Undo the most recent undoable action in the application history.
• Redo: Redo a previously undone action.
• StartCommandServer: Start the local command server if it is not already running.
• StopCommandServer: Stop the local command listener.