Data Output Structure

Overview

All utility measurement workflows return comprehensive data structures containing measurements, images, scaling information, and metadata. The data is returned as CloneableJSON, a swifty way to work with our custom JSON format that preserves complex data relationships and enables precise data extraction.

CloneableJSON Format

CloneableJSON is a specialized JSON format that can contain:

• Standard JSON types: strings, numbers, booleans, arrays, objects

• Custom data types: images, locations, bounding boxes, UUIDs

• Nested structures: Complex hierarchical data with type preservation

• Metadata: Scaling data, coordinate mappings, and measurement context

• Codeable: Easily dump to a JSON string

See the CloneableJSON Documentation for practical examples of accessing the measurement outputs

CloneableJSON Documentation

Complete Pole Measurement Output

Here's the complete structure returned from a pole measurement:

{
    "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