Data output structure

Overview

Utility measurement workflows return measurements, images, scaling information, and metadata. The SDK returns data as CloneableJSON.

CloneableJSON Format

CloneableJSON can contain:

Standard JSON types: Strings, numbers, booleans, arrays, and objects.
Custom data types: Images, locations, bounding boxes, and UUIDs.
Nested structures: Hierarchical data with type preservation.

See the CloneableJSON guide for measurement output examples.

CloneableJSON documentation

Complete pole measurement output

A pole measurement returns this structure:

{
    "high_accuracy": true,
    "pole_information": {
        "height": 35.2,
        "lean_angle": 2.1,
        "lean_direction": 45.7,
        "location": {
            "latitude": 40.7128,
            "longitude": -74.0060,
            "altitude": 25.1
        }
    },
    "attachments": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "type": "transformer",
            "classification": "Distribution Transformer",
            "inventoryClass": {
                "name": "Distribution Transformer",
                "subcategories": [
                    {
                        "name": "KVA Rating",
                        "value": "50",
                        "required": true
                    },
                    {
                        "name": "Phase",
                        "value": "Single",
                        "required": true
                    }
                ]
            },
            "owner": "City Power & Light",
            "height": 25.3,
            "distanceFromPoleTop": 9.9,
            "relatedGuys": ["guy-uuid-1"],
            "images": [
                {
                    "imageId": "image-uuid-1",
                    "point": {
                        "x": 150.5,
                        "y": 200.2
                    }
                }
            ],
            "notes": "Transformer shows signs of corrosion on tank"
        }
    ],
    "images": [
        {
            "id": "image-uuid-1",
            "type": "pole",
            "image": "CloneableImage data",
            "referenceLine": {
                "bottom": {
                    "id": "point-bottom-uuid",
                    "pixelCoordinates": {
                        "x": 100.0,
                        "y": 500.0
                    },
                    "worldCoordinates": {
                        "x": 0.0,
                        "y": 0.0,
                        "z": 0.0
                    }
                },
                "top": {
                    "id": "point-top-uuid",
                    "pixelCoordinates": {
                        "x": 100.0,
                        "y": 50.0
                    },
                    "worldCoordinates": {
                        "x": 0.0,
                        "y": 35.2,
                        "z": 0.0
                    }
                }
            },
            "scalingData": {
                "pixelArray": [
                    {
                        "id": "pixel-point-1",
                        "pixelCoordinates": {
                            "x": 100.0,
                            "y": 275.0
                        },
                        "worldCoordinates": {
                            "x": 0.0,
                            "y": 17.6,
                            "z": 0.0
                        }
                    },
                    {
                        "id": "pixel-point-2",
                        "pixelCoordinates": {
                            "x": 150.5,
                            "y": 200.2
                        },
                        "worldCoordinates": {
                            "x": 0.5,
                            "y": 25.3,
                            "z": 0.2
                        }
                    }
                ]
            },
            "cameraTilt": 15.2,
            "predictedCameraTilt": 14.8,
            "wasAutoCaptured": false,
            "wasCapturedInSafeZone": true,
            "stickDistance": 3.5,
            "stickHeight": 1.8,
            "captureTimestamp": "2024-01-15T14:30:25.123Z"
        }
    ]
}

Midspan measurement output

Midspan shares the same data structure as poles.

Guy wire measurement output

Guy wire measurements return a specialized GuyAnchorVector structure:

// Direct return type for guy measurements
public struct GuyAnchorVector: Equatable {
    var id: UUID
    var vector: SIMD3<Float>        // 3D vector from pole base to anchor
    var leadLength: Float           // Distance in feet
    var angle: Float               // Degrees from true north
    var creationMethod: GuyAnchorCreationMethod
}

// When integrated with pole data, appears as:
{
    "guy_measurement": {
        "id": "guy-anchor-uuid",
        "vector": {"x": 10.5, "y": 0.0, "z": 8.2},
        "leadLength": 13.2,
        "angle": 38.0,
        "creationMethod": "measured",
        "anchor_location": {
            "latitude": 40.7129,
            "longitude": -74.0059,
            "calculated_from_pole": true
        }
    }
}

Data type categories

Measurement Data

Dimensional measurements: Heights, distances, angles, coordinates
Location data: GPS coordinates with accuracy metadata
Structural data: Lean angles, orientations, vectors

Visual Data

Images: High-resolution photos with embedded metadata
Scaling data: Pixel-to-world coordinate mappings
Reference points: Calibration and measurement reference markers

Classification Data

Inventory classes: Hierarchical equipment categorization
Subcategories: Detailed equipment specifications
Relationships: Connections between equipment, spans, and guys

Image data structure

Images contain multiple layers of information:

Measurement References

Represents the measurement line on the image. Measurements are taken along this line.

{
    "referenceLine": {
        "bottom": {
            "id": "reference-point-id",
            "pixelCoordinates": {"x": 100, "y": 500},
            "worldCoordinates": {"x": 0, "y": 0, "z": 0}
        },
        "top": {
            "id": "reference-point-id",
            "pixelCoordinates": {"x": 100, "y": 50},
            "worldCoordinates": {"x": 0, "y": 35.2, "z": 0}
        }
    }
}

Scaling Data

We provide an array of pixels and associated 3d coordinates for each pixel along the measurement reference line. The pixel data will allow for additional measurements to be made after the data collection has been completed.

{
    "scalingData": {
        "pixelArray": [
            {
                "id": "scaling-point-id",
                "pixelCoordinates": {"x": 150.5, "y": 200.2},
                "worldCoordinates": {"x": 0.5, "y": 25.3, "z": 0.2}
            }
        ]
    }
}

Image Metadata

{
    "cameraTilt": 15.2,
    "predictedCameraTilt": 14.8,
    "coreMotionTilt": 15.0,
    "wasAutoCaptured": false,
    "wasCapturedInSafeZone": true,
    "stickDistance": 3.5,
    "stickHeight": 1.8
}

Attachment data structure

Attachments include comprehensive classification and measurement data:

Basic Attachment Properties

{
    "id": "attachment-uuid",
    "type": "attachment|guy|wire",
    "classification": "human-readable classification from the inventoryClass",
    "height": 25.3,
    "distanceFromPoleTop": 9.9
}

Inventory Classification

{
    "inventoryClass": {
        "name": "Distribution Transformer",
        "subcategories": [
            {
                "name": "KVA Rating",
                "description": "KVA Rating"
            }
        ]
    }
}

Relationships

{
    "owner": "utility owner name",
    "relatedSpans": ["span-uuid-1", "span-uuid-2"],
    "relatedGuys": ["guy-uuid-1"],
    "images": [
        {
            "imageId": "image-uuid",
            "point": {"x": 150.5, "y": 200.2}
        }
    ]
}

Coordinate systems

Pixel Coordinates

Origin: Top-left corner of image (0,0)
Units: Pixels
Y-axis: Increases downward

World Coordinates

Units: Meters
Y-axis: Height above ground (increases upward)
X-axis: East-west offset from pole center
Z-axis: North-south offset from pole center

Geographic Coordinates

Format: WGS84 decimal degrees
Altitude: Meters above sea level
Accuracy: Horizontal and vertical accuracy in meters

Get started

iOS SDK

Data output structure

Overview

CloneableJSON Format

CloneableJSON documentation

Complete pole measurement output

Midspan measurement output

Guy wire measurement output

Data type categories

Measurement Data

Visual Data

Classification Data

Image data structure

Measurement References

Scaling Data

Image Metadata

Attachment data structure

Basic Attachment Properties

Inventory Classification

Relationships

Coordinate systems

Pixel Coordinates

World Coordinates

Geographic Coordinates

Get started

iOS SDK

​Overview

​CloneableJSON Format

CloneableJSON documentation

​Complete pole measurement output

​Midspan measurement output

​Guy wire measurement output

​Data type categories

​Measurement Data

​Visual Data

​Classification Data

​Image data structure

​Measurement References

​Scaling Data

​Image Metadata

​Attachment data structure

​Basic Attachment Properties

​Inventory Classification

​Relationships

​Coordinate systems

​Pixel Coordinates

​World Coordinates

​Geographic Coordinates

Overview

CloneableJSON Format

Complete pole measurement output

Midspan measurement output

Guy wire measurement output

Data type categories

Measurement Data

Visual Data

Classification Data

Image data structure

Measurement References

Scaling Data

Image Metadata

Attachment data structure

Basic Attachment Properties

Inventory Classification

Relationships

Coordinate systems

Pixel Coordinates

World Coordinates

Geographic Coordinates