Pinchot API v16 Migration

Changes were included in Version 16 of the Pinchot API to facilitate new ways of scanning with greater flexibility. Developers using previous versions of the API should review the new characteristics below as some work will typically be required to migrate forward existing applications.

Scan System Initialization

The Scan System is now initialized with a selection of units, either inches or millimeters. Previously all configuration and data was only done in inches. With these changes, the units can be selected upon creation of the scan system and will be carried through all subsequent functions that have fields with dimensional units.

Pinchot v13 .NET API

public ScanSystem()

Pinchot v16 .NET API

public enum ScanSystemUnits
{
    Invalid = 0,
    Inches,
    Millimeters
}

public ScanSystem(ScanSystemUnits units)

Pinchot v13 C API

jsScanSystem jsScanSystemCreate();

Pinchot v16 C API

typedef enum {
  JS_UNITS_INVALID = 0,
  JS_UNITS_INCHES = 1,
  JS_UNITS_MILLIMETER = 2,
} jsUnits;

jsScanSystem jsScanSystemCreate(
  jsUnits units);

Scan Head Discovery

A new approach to discover JS-50 scan heads on the network was implemented in v16. This makes it possible to search for scan heads that can be assigned to a given scan system before connecting.

Pinchot v16 C API

typedef struct {
  uint32_t serial_number;
  uint32_t ip_addr;
  jsScanHeadType type;
  char type_str[JS_SCAN_HEAD_TYPE_STR_MAX_LEN];
  uint32_t firmware_version_major;
  uint32_t firmware_version_minor;
  uint32_t firmware_version_patch;
} jsDiscovered;

int jsScanSystemDiscover(
  jsScanSystem scan_system);

int jsScanSystemGetDiscovered(
  jsScanSystem scan_system,
  jsDiscovered *results,
  uint32_t max_results);

Pinchot v16 .NET API

public class DiscoveredDevice
{
    public uint SerialNumber { get; internal set; }

    public ScanHeadVersionInformation Version { get; internal set; }

    public string ProductName { get; internal set; }

    public IPAddress IpAddress { get; internal set; }

    public string State { get; internal set; }

    public bool IsCompatibleWithApi()

    internal IPAddress ClientIpAddress { get; set; }
}

public partial class ScanSystem
{
    public Dictionary<uint, DiscoveredDevice> DiscoverDevices()

    public async Task<Dictionary<uint, DiscoveredDevice>> DiscoverDevicesAsync()
}

Camera / Laser Enums

The enumerated values for both camera and lasers have been modified to have value 0 indicate an invalid value. Care should be taken if using these values for indexing into an array.

Pinchot v16 .NET API

public enum Camera
{
    Invalid = 0,
    CameraA,
    CameraB,
}

public enum Laser
{
    Invalid = 0,
    Laser1,
    Laser2,
    Laser3,
    Laser4,
    Laser5,
    Laser6,
}

Pinchot v16 C API

typedef enum {
  JS_CAMERA_INVALID = 0,
  JS_CAMERA_A = 1,
  JS_CAMERA_B,
  JS_CAMERA_MAX,
} jsCamera;

typedef enum {
  JS_LASER_INVALID = 0,
  JS_LASER_1 = 1,
  JS_LASER_2,
  JS_LASER_3,
  JS_LASER_4,
  JS_LASER_5,
  JS_LASER_6,
  JS_LASER_MAX,
} jsLaser;

Scan Period

With release version 16, the scan system is now commanded to scan at a given period rather than at a given rate. This was necessary due to changes regarding how phasing is implemented and allows for a common time base across the API; making for simple comparisons across other parameters such as laser on time.

Camera & Laser Functions

In both the .NET and C API, there are functions that operate on particular cameras and lasers of a given scan head. For .NET, these functions use overloads to allow the same function to be called using different arguments. In the C API however, since it lacks overloading, function names are post fixed with either Camera or Laser. The correct function to call depends on the JS-50 scan head type being utilized. The need for this approach is due to differences in how particular JS-50s perform their scanning. A summary of which scan head uses camera or laser function is provided below.

JS-50 WX: Camera
JS-50 WSC: Camera
JS-50 X6B20: Laser
JS-50 X6B30: Laser

Phase Table

Previously, phasing was done by specifying a time offset for a given scan head when configuring it. This time offset had to be calculated by the end user and was only able to configure at the the scan head level. With version 16, the concept of a Phase Table was introduced to facilitate phased scanning. Documentation of the phase table can be found in it's corresponding article.

When using the phase table, it is important to keep in mind that the phase table uses phased elements rather than the just the scan head itself. This allows scheduling of particular cameras & lasers, granting control and flexibility to the user, rather than forcing a particular phasing scheme.

Profile Sequence Number

A sequence number has been added to profile data to assist in tracking which profiles belong together. This number will increment each time the scan period has elapsed and all phases in the phase table have completed their scans.

Scan Head Cable Orientation

The cable orientation was removed from the alignment parameters and is set independently. This removed the possibility of setting conflicting cable orientations for the same scan head when setting up individual lasers / cameras.

Pinchot v13 .NET API

public partial class ScanHead : IDisposable
{
    public void SetAlignment(double rollDegrees,
                             double shiftX,
                             double shiftY,
                             ScanHeadOrientation orientation)
}

Pinchot v16 .NET API

public partial class ScanHead : IDisposable
{
    public ScanHeadOrientation Orientation

    public void SetAlignment(double rollDegrees,
                             double shiftX,
                             double shiftY)
}

Pinchot v13 C API

int32_t jsScanHeadSetAlignment(
  jsScanHead scan_head,
  double roll_degrees,
  double shift_x,
  double shift_y,
  bool is_cable_downstream);

int32_t jsScanHeadSetAlignmentCamera(
  jsScanHead scan_head,
  jsCamera camera,
  double roll_degrees,
  double shift_x,
  double shift_y,
  bool is_cable_downstream);

Pinchot v16 C API

int32_t jsScanHeadSetAlignment(
  jsScanHead scan_head,
  double roll_degrees,
  double shift_x,
  double shift_y);

int32_t jsScanHeadSetAlignmentCamera(
  jsScanHead scan_head,
  jsCamera camera,
  double roll_degrees,
  double shift_x,
  double shift_y);

int32_t jsScanHeadSetAlignmentLaser(
  jsScanHead scan_head,
  jsLaser laser,
  double roll_degrees,
  double shift_x,
  double shift_y);

int32_t jsScanHeadSetCableOrientation(
  jsScanHead scan_head,
  jsCableOrientation cable_orientation)

C API Object Data Type Change

The underlying data type for the jsScanSystem and jsScanHead object was changed in version 16 due to changes in internal code. The changes also prevent the possibility of accidentally using a NULL object.

Pinchot v13 C API

typedef void *jsScanSystem;
typedef void *jsScanHead;

Pinchot v16 C API

typedef int64_t jsScanSystem;
typedef int64_t jsScanHead;