FindSurface Response from Web

By requested URL, FindSurface server provides two types of response, one is binary format and another one is JSON format.

1. HTTP Response Binary Format

1.1 HTTP Response Header

Required Fields

Header Name	Header Value
Content-Type	application/x-findsurface-response

Optional Fields

NOTE: To use optional header field(s) below, Content-Type must be application/x-findsurface-response.

Header Name	Header Value
X-Content-Endian	big

If X-Content-Endian is presented, it lets the client know a byte order of a response body as Big-endian. Otherwise, as Little-endian.

1.2 HTTP Response Body Format

Response body only has Header part in most of the cases.
But if you specify an option flag for [Request Inlier & Outlier Flags] on request, Array of Inlier & Outlier Flag will be attached after Header.

Body Header
01	02	03	04
Signature		Version
Header Size
Result Code

If, FindSurface has been succeeded ( Result Code > 0 ), followings will be added.

Result Code > 0
01	02	03	04
Data Length
RMS

Case 1. Plane Parameter ( Result Code == 1 )

Plane Parameter (Result Code == 1)
01	02	03	04
X of Lower-Left Position
Y of Lower-Left Position
Z of Lower-Left Position
X of Lower-Right Position
Y of Lower-Right Position
Z of Lower-Right Position
X of Upper-Right Position
Y of Upper-Right Position
Z of Upper-Right Position
X of Upper-Left Position
Y of Upper-Left Position
Z of Upper-Left Position

Case 2. Sphere Parameter ( Result Code == 2 )

Sphere Parameter (Result Code == 2)
01	02	03	04
X of Center Position
Y of Center Position
Z of Center Position
Radius

Case 3. Cylinder Parameter ( Result Code == 3 )

Cylinder Parameter (Result Code == 3)
01	02	03	04
X of Bottom Position
Y of Bottom Position
Z of Bottom Position
X of Top Position
Y of Top Position
Z of Top Position
X of Radius

Case 4. Cone Parameter ( Result Code == 4 )

Cone Parameter (Result Code == 4)
01	02	03	04
X of Bottom Position
Y of Bottom Position
Z of Bottom Position
X of Top Position
Y of Top Position
Z of Top Position
Bottom Radius
Top Radius

Case 5. Torus Parameter ( Result Code == 5 )

Torus Parameter (Result Code == 5)
01	02	03	04
X of Center Position
Y of Center Position
Z of Center Position
X of Normal Vector
Y of Normal Vector
Z of Normal Vector
Mean Radius
Tube Radius

If [Reqeust Inlier & Outlier Flags] flag is specified on reuqest header, followings will be added.

Array of In/Outliers flag
01	02	…	…	…	n**
flag[0]	flag[1]	…	…	…	flag[n - 1]

** n == Data Length

1.2.1. Common Body Header Description

Signature uint8_t[2]

"FS" : Signature bytes. [0] = 'F'; [1] = 'S'

Version uint8_t[2]

Version. [0] = major, [1] = minor
Current version is 1.0 ( major = 1, minor = 0 )

Header Size uint32_t

Byte size of this header. ( >= 12 )
This value varies with the Result Code.
But, minimum value is 12. ( when FindSurface has been failed. )

Result Code int32_t

Result code of FindSurface.

< 0 : Unexpected error
0 : Not found
1 : Plane has been found
2 : Sphere has been found
3 : Cylinder has been found
4 : Cone has been found
5 : Torus has been found

Data Length uint32_t

Byte size of body data right after this header.
Most of the cases this value is '0'. But if you specify an option flag for [Request Inlier & Outlier Flags], this value indicates that size of the Array of Inlier & Outlier Flag.

This value is only available when Result Code > 0.

RMS float (IEEE754 Single)

Resultant RMS fit error of the inliers.

This value is only available when Result Code > 0.

1.2.2. Body Header Result Parameter Description

Case 1. Plane Parameter ( Result Code == 1 )

X of Lower-Left Position float (IEEE754 Single): The X coordinates of lower left corner.
Y of Lower-Left Position float (IEEE754 Single): The Y coordinates of lower left corner.
Z of Lower-Left Position float (IEEE754 Single): The Z coordinates of lower left corner.
X of Lower-Right Position float (IEEE754 Single): The X coordinates of lower right corner
Y of Lower-Right Position float (IEEE754 Single): The Y coordinates of lower right corner
Z of Lower-Right Position float (IEEE754 Single): The Z coordinates of lower right corner
X of Upper-Right Position float (IEEE754 Single): The X coordinates of upper right corner
Y of Upper-Right Position float (IEEE754 Single): The Y coordinates of upper right corner
Z of Upper-Right Position float (IEEE754 Single): The Z coordinates of upper right corner
X of Upper-Left Position float (IEEE754 Single): The X coordinates of upper left corner
Y of Upper-Left Position float (IEEE754 Single): The Y coordinates of upper left corner
Z of Upper-Left Position float (IEEE754 Single): The Z coordinates of upper left corner

Case 2. Sphere Parameter ( Result Code == 2 )

X of Center Position float (IEEE754 Single): The X coordinates of center.
Y of Center Position float (IEEE754 Single): The Y coordinates of center.
Z of Center Position float (IEEE754 Single): The Z coordinates of center.
Radius float (IEEE754 Single): The radius.

Case 3. Cylinder Parameter ( Result Code == 3 )

X of Bottom Position float (IEEE754 Single): The X coordinates of center of bottom circle.
Y of Bottom Position float (IEEE754 Single): The Y coordinates of center of bottom circle.
Z of Bottom Position float (IEEE754 Single): The Z coordinates of center of bottom circle.
X of Top Position float (IEEE754 Single): The X coordinates of center of top circle.
Y of Top Position float (IEEE754 Single): The Y coordinates of center of top circle.
Z of Top Position float (IEEE754 Single): The Z coordinates of center of top circle.
Radius float (IEEE754 Single): The radius.

Case 4. Cone Parameter ( Result Code == 4 )

X of Bottom Position float (IEEE754 Single): The X coordinates of center of bottom circle.
Y of Bottom Position float (IEEE754 Single): The Y coordinates of center of bottom circle.
Z of Bottom Position float (IEEE754 Single): The Z coordinates of center of bottom circle.
X of Top Position float (IEEE754 Single): The X coordinates of center of top circle.
Y of Top Position float (IEEE754 Single): The Y coordinates of center of top circle.
Z of Top Position float (IEEE754 Single): The Z coordinates of center of top circle.
Bottom Radius float (IEEE754 Single): The radius of bottom (larger) circle.
Top Radius float (IEEE754 Single): The radius of top (smaller) circle.

Case 5. Torus Parameter ( Result Code == 5 )

X of Center Position float (IEEE754 Single): The X coordinates of center.
Y of Center Position float (IEEE754 Single): The Y coordinates of center.
Z of Center Position float (IEEE754 Single): The Z coordinates of center.
X of Normal Vector float (IEEE754 Single): The X of the axis (normal vector).
Y of Normal Vector float (IEEE754 Single): The Y of the axis (normal vector).
Z of Normal Vector float (IEEE754 Single): The Z of the axis (normal vector).
Mean Radius float (IEEE754 Single): The mean radius.
Tube Radius float (IEEE754 Single): The tube (circle) radius.

1.2.3. Body Data (Array of In/Outliers Flag) Description

Note: This value is only available when you specify option flag of [Request Inlier & Outlier Flags] on request header.

flag[n] uint8_t

This value that indicates either Inliers or Outliers. ( 0 <= n < Data Length )

0x00 - Inliers
otherwise - Outliers

An index order of this array is same as Array of Point Attributes on the requested body. The i th flag indicates whether the i th point in the requested body is an inlier or an outlier. The outliers may be used as the new Point Attributes array in the next requested body to be sent.

1.3. Response Body Data Example

Example 1

Case) When FindSurface has been failed.

Offset	Size	Hex value	Value	Description
Header Only
0x00	2	`46 53`	"FS"	Signature field
0x02	2	`01 00`	1.0	Version
0x04	4	`0C 00 00 00`	12 bytes	Byte size of this header
0x08	4	`00 00 00 00`	Not Found	Result Code

Example 2

Case) When FindSurface has been succeeded to find a Plane. The measurement unit is in meter.

Let's assume that the result of each coordinate of the corners of the plane is:

Lower-Left: [ -0.1, -0.1, 0.1 ]
Lower-Right: [ 0.1, 0.0, 0.1 ]
Upper-Right: [ 0.1, 0.1, -0.1 ]
Upper-Left: [ -0.1, 0.0, -0.1 ]

Offset	Size	Hex value	Value	Description
Header with Parameter
0x00	2	`46 53`	"FS"	Signature field
0x02	2	`01 00`	1.0	Version
0x04	4	`44 00 00 00`	68 bytes	Byte size of this header (include parameter)
0x08	4	`01 00 00 00`	Plane	Result Code
0x0C	4	`00 00 00 00`	0 bytes	No data after this Header
0x10	4	`A6 9B C4 3A`	1.5 mm fit error	Resultant RMS fit error of the inliers.
Plane Parameter
0x14	4	`CD CC CC BD`	-0.1	The x coordinates of lower-left corner.
0x18	4	`CD CC CC BD`	-0.1	The y coordinates of lower-left corner.
0x1C	4	`CD CC CC 3D`	0.1	The z coordinates of lower-left corner.
0x20	4	`CD CC CC 3D`	0.1	The x coordinates of lower-right corner.
0x24	4	`00 00 00 00`	0.0	The y coordinates of lower-right corner.
0x28	4	`CD CC CC 3D`	0.1	The z coordinates of lower-right corner.
0x2C	4	`CD CC CC 3D`	0.1	The x coordinates of upper-right corner.
0x30	4	`CD CC CC 3D`	0.1	The y coordinates of upper-right corner.
0x34	4	`CD CC CC BD`	-0.1	The z coordinates of upper-right corner.
0x38	4	`CD CC CC BD`	-0.1	The x coordinates of upper-left corner.
0x3C	4	`00 00 00 00`	0.0	The y coordinates of upper-left corner.
0x40	4	`CD CC CC BD`	-0.1	The z coordinates of upper-left corner.