Chicago LSM HTTP RESTful WebServices Interface

Chicago Laser Scanning Microscope provides a RESTful web interface so that the clients and develop their own higher level application without code modification by SpecialtyCircuits.

Below are the description and explanation of each API.
(If you have the executable running on your computer, you can click the link to directly access some of the API call via browser.)

http://localhost:38080/scclsm/get-identification (GET)

get-identification returns the following example json strings to indicate the basic instrument Information.

{
    "HostExecutable": {
        "FileVersion": "25.2.12.931",
        "ProductName": "CLSM with HTTP RESTful Interface",
        "InternalName": "CLSM",
        "CompanyName": "SpecialtyCircuits LLC",
        "LegalCopyright": "(C) 2014-2025 SpecialtyCircuits LLC",
        "FileDescription": "CLSM(ADP3450)- AppWebServer"
    },
    "Controller": {
        "SN": "SN:210321B5D507",
        "Model": "Analog Discovery 2",
        "DriverVersion": "3.23.4"
    }
}

http://localhost:38080/scclsm/get-image-param (GET)

get-image-param returns the default image parameters upon instrument core boot up. It is recommended that the higher level application pull this information first before proceeding with any image scan to preserve consistency between higher level application and lower level controller.
```
{
  "Resolution": {
    "X(pix)": 32,
    "Y(pix)": 32
  },
  "Origin": {
    "X(m)": 0,
    "Y(m)": 0
  },
  "Raster": {
    "Size-X(m)": 0.00001,
    "Size-Y(m)": 0.00001,
    "Shear(deg)": 0,
    "Rotation(deg)": 0
  },
  "DefCal": {
    "Scale-X(V/m)": 10000,
    "Scale-Y(V/m)": 10000,
    "Shear(deg)": 0,
    "Rotation(deg)": 0
  },
  "AdvParam": {
    "DwellTime(s)": 0.000001,
    "VideoSampleRate(Hz)": 100000000,
    "PixelOversampling": 1,
    "LineOversampling": 1,
    "FrameOversampling": 1,
    "WaveformType": 1,
    "ScannerOversampling": 1,
    "Retrace(pix)": 0
  }
}
```
Resolution is self explanatory.
Origin is give the raster image a translation shift from the center of the field-of-view. It is defined as a vector of the image center to the hardware field-of-view center.
Raster is used to shape how the image scanning area.
Size-X, Size-Y and Rotation are self-explanatory. Shear is defined as the angle between the secondary scan axis to the vertical axis.
DefCal is used to correct linear space distortion back to ideal orthogonal grid.
Size-X, Size-Y and Rotation are self-explanatory. Shear is defined as the angle between the secondary scan axis to the vertical axis. Note that the sign negates in all parameters related to an angle. Scale behave like as reciprocal of themselves as in Raster. More detailed explanation of Raster and DefCal can be found at [placeholder]
DwellTime is the time spend on each pixel in the final image (not as sampled acquired from digitizer.) DwellTime must be whole number times of the clock period. A warning will be generated if a fractional number of clock dwell time is set.
VideoSampleRate is the clock rate of the digitizer.
PixelOversampling, aka, pixel averaging, is used to acquire multiple samples per pixel. It does not change the pixel dwell time. DwellTime / Pixeloversampling must be a whole number times of clock period. Increasing PixelOversampling will not increase total time of the image.
LineOversampling, aka Line averaing, is to sample each line scan multiple time. Increasing LineOversamping will increase total time of the image.
FrameOversampling, aka image averaging, is to sample each image scan multiple time. Increasing LineOversamping will increase total time of the image.
(not implemented yet) Retrace is the addition dummy pixels added to the beginning of each scan path to account of finite turnaround time of the scanner mirror. Signal during Retrace will not be included in greyscale and color image output, but will be included in raw output.
WaveformType is used to set how the scan path is constructed.

Due to the limitation of the handling of enum in LabVIEW json format. All the enum had to converted to numeric representation. To parse the numeric option into meaningful strings, use the following table.

0: StairCaseRamp_FullDoF
1: Serpentine_FullDoF
2: Ramp
3: StairCaseRamp
4: Serpentine

For more detail explanation of the difference between each type, refer to [placeholder].

All numbers in the JSON strings strictly follow SI units, unless otherwise stated.
http://localhost:38080/scclsm/set-image-param (PUT)

set-image-param is used to set the image scanning condition. The API will take a JSON string in the same format as in get-image-param and store it in a cache. A subsequent API call of commit-image or snap must be called for any parameter change to become effective.
The rational behind this behavior is for the higher level application to create wrapper API calls for each individual parameters. When each individual parameter update being requested only cache is updated, not actual hardware configuration. This reduces overhead, latency, and wear of mechanical parts, when higher level application prefer to update parameters one by one. Commit changes only once after all parameters have been updated.
http://localhost:38080/scclsm/commit-image (POST)

commit-image will apply all the changes that previous requested by set-image-param to actual hardware. It must be called after image conditions changes and prior to get-image-time, get-image-greyscale-png, get-image-color-png.
http://localhost:38080/scclsm/get-image-time (GET)
```
{
    "Target Time(ms)": 100
}
```
get-image-time will return an estimated time of the image acquisition. This time is needed to set the timeout when snap is called.
Note that a reasonable additional amount of time, eg 100 ms, need to be added to the Target Time when setting up timeout in snap API call, to account for HTTP communication latency.

http://localhost:38080/scclsm/snap?timeout=1000 (GET)

{
  "Timestamp(ISO8601)": "2025-03-14T23:33:10.784-07:00",
  "ImageParam": {
    "Resolution": {
      "X(pix)": 128,
      "Y(pix)": 192
    },
    "Origin": {
      "X(m)": 0,
      "Y(m)": 0
    },
    "Raster": {
      "Size-X(m)": 0.00001,
      "Size-Y(m)": 0.00001,
      "Shear(deg)": 0,
      "Rotation(deg)": 0
    },
    "DefCal": {
      "Scale-X(V/m)": 10000,
      "Scale-Y(V/m)": 10000,
      "Shear(deg)": 0,
      "Rotation(deg)": 0
    },
    "AdvParam": {
      "DwellTime(s)": 0.000001,
      "VideoSampleRate(Hz)": 100000000,
      "PixelOversampling": 4,
      "LineOversampling": 1,
      "FrameOversampling": 1,
      "WaveformType": 4,
      "ScannerOversampling": 1,
      "Retrace(pix)": 0
    }
  }
}

snap triggers a new image snap in the controller. It will return the meta data of the image when the acquisition is done. The meta data contains the timestamp in ISO1861 (RFC3339) format and the image parameter with same data structure as in the get-image-param return.
The timestamp reflects the time when the image trigger was sent to the hardware, so it at the beginning of each image.
snap API call implies commit-image if not called prior to snap.
The higher level software should call get-image-greyscale, get-image-raw or get-image-color to get the images in PNG or raw binary format.

http://localhost:38080/scclsm/get-image-greyscale-png?channel=0 (GET)

get-image-greyscale returns an image in PNG format. A JSON string must be passed to the server to set which channel to export.
Option channel is to set which channel to export. Valid values of channel include 0,1,2,3. If not present, channel 0 will be returned.
http://localhost:38080/scclsm/get-image-raw?channel=0 (GET)

get-image-raw returns an image in raw binary. Higher level application is responsible to reconstruct the binary raw data into an image.
Option channel is to set which channel to export. Valid values of channel include 0,1,2,3. If not present, channel 0 will be returned.

Details on the reconstruction refers to [placeholder].
http://localhost:38080/scclsm/get-image-color-png (GET)

get-image-color returns an 8-bit color image, with transparency, in PNG format.
Option channelmap is used to assign mapping between color and input signal channel. If left empty, Red, Green, Blue, and Alpha are assigned to Channel 0, 1, 2, and 3 respectively.
http://localhost:38080/scclsm/save-as-default-settings (POST)

save-as-default-settings will commit the existing imaging condition into the underlying configuration data of the core image scanning controller. Once saved in the database, the image scanning core software will startup with the new configuration for all future operation.
http://localhost:38080/scclsm/exit (POST)

exit will exiting the sequence to gracefully shutdown the controller. This API is the only way to gracefully shutdown the application, if --nogui command line argument is supplied upon startup. (For non-graceful shutdown, use Task Manager to kill the program.)