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
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
Last updated