Feature Request: Add Polyline Shape Support to ETL Framework Properties

[chriselsen]

Problem Statement

The current ETL framework only supports shape.ellipse in feature properties, preventing the implementation of expiring polygons that are critical for time-sensitive geospatial data like emergency alerts.

ATAK-CIV Drawing Shape Expiration Issue

ATAK-CIV has a fundamental limitation with polygon expiration:

• Marker objects (a-f-*, a-h-*, etc.) properly expire based on their stale time
• DrawingShape objects (u-d-f, u-d-p) persist indefinitely regardless of their stale time
• This causes maps to become cluttered with expired alert areas and outdated information
• No automatic cleanup mechanism exists for drawing shapes

The node-CoT Solution Pattern

node-CoT supports creating expiring polygons using a Marker with an associated <shape><polyline> detail. When the marker expires, ATAK automatically removes the associated polygon.

Working Example from node-CoT

import CoT from 'node-cot';

const expiringPolygon = new CoT({
    event: {
        _attributes: {
            version: "2.0",
            uid: "expiring-polygon-123",
            type: "a-f-G",  // Expirable marker type (friendly ground)
            time: "2024-01-01T12:00:00Z",
            start: "2024-01-01T12:00:00Z", 
            stale: "2024-01-01T13:00:00Z"  // Expires in 1 hour
        },
        point: {
            _attributes: {
                lat: 39.0981196,    // Polygon center point
                lon: -108.7395013,
                hae: 0.0,
                ce: 9999999.0,
                le: 9999999.0
            }
        },
        detail: {
            contact: {
                _attributes: { callsign: "Alert Zone" }
            },
            shape: {
                polyline: {
                    _attributes: { 
                        closed: true,           // Makes it a polygon
                        fillColor: "#FF0000",   // Red fill
                        color: "#000000"        // Black outline
                    },
                    vertex: [
                        { _attributes: { lat: 39.1, lon: -108.4 } },
                        { _attributes: { lat: 39.1, lon: -108.5 } },
                        { _attributes: { lat: 39.0, lon: -108.5 } },
                        { _attributes: { lat: 39.0, lon: -108.4 } },
                        { _attributes: { lat: 39.1, lon: -108.4 } }  // Close polygon
                    ]
                }
            }
        }
    }
});

Key Technical Requirements

1. Expirable Marker Types (these work with expiration):

   • a-f-G (friendly ground)
   • a-h-G (hostile ground)
   • a-n-G (neutral ground)
   • a-u-G (unknown ground)
   • a-f-X-i (friendly incident)

2. Avoid Drawing Shape Types (these don't expire):

   • u-d-p (drawing point)
   • u-d-f (drawing polygon)

3. Polygon Structure Requirements:

   • Set closed: true in polyline attributes to create a filled polygon
   • First and last vertex should be identical to properly close the polygon
   • Use fillColor for interior color, color for outline
   • Support semi-transparent fills (e.g., #80FF0000 for 50% transparent red)

4. Expiration Behavior:

   • ✅ Marker expires based on stale time
   • ✅ Associated polygon is automatically removed
   • ✅ Both disappear from ATAK when expired
   • ✅ Solves the persistent polygon problem in ATAK-CIV

Current ETL Framework Limitation

The ETL framework's feature properties schema only supports ellipse shapes:

// Current - only supports ellipse
shape: Type.Optional(Type.Object({
    ellipse: Type.Optional(ShapeEllipseAttributes)
}))

However, the underlying node-CoT types.ts already defines ShapePolyLine support:

export const ShapePolyLineAttributes = Type.Object({
    closed: Type.Optional(Type.Boolean()),
    fillColor: Type.Optional(Type.String()),
    color: Type.Optional(Type.String()),
})

export const ShapePolyLine = Type.Object({
    _attributes: Type.Optional(ShapePolyLineAttributes),
    vertex: Type.Optional(Type.Union([
        Type.Object({
            _attributes: VertexAttribute
        }),
        Type.Array(Type.Object({
            _attributes: VertexAttribute
        }))
    ]))
})

export const Shape = Type.Object({
    polyline: Type.Optional(ShapePolyLine),
    ellipse: Type.Optional(ShapeEllipse),
    link: Type.Optional(Type.Union([Type.Array(ShapeLink), ShapeLink]))
})

Requested Enhancement

Update the ETL framework's feature properties schema to match the underlying node-CoT capabilities:

// Proposed - add polyline support to match node-CoT
shape: Type.Optional(Type.Object({
    ellipse: Type.Optional(ShapeEllipseAttributes),
    polyline: Type.Optional(ShapePolyLineAttributes)
}))

Where ShapePolyLineAttributes includes:

• _attributes: { closed?: boolean, fillColor?: string, color?: string }
• vertex: Array<{ _attributes: { lat: number, lon: number } }>

Use Case: CAP Emergency Alert Polygons

Emergency alerts (CAP-NZ, CAP-US, etc.) include polygon areas that must expire when the alert expires. Currently:

1. Problem: Creating separate polygon features results in persistent shapes that never expire
2. Workaround: Complex dual-feature approach (polygon + marker) with inconsistent behavior
3. Solution: Single expiring marker with polyline shape for clean automatic expiration

Real-World Impact

• Weather Alerts: Storm warning areas that should disappear when warnings expire
• Emergency Zones: Evacuation areas that should clear when incidents resolve
• Temporary Restrictions: Airspace or maritime restrictions with defined time limits
• Operational Areas: Military or emergency service zones with time-based validity

Benefits

1. Automatic Expiration: Both marker and polygon disappear together based on stale time
2. Reduced Feature Count: Single feature instead of separate polygon + marker
3. ATAK Compatibility: Works with existing ATAK expiration mechanisms
4. Clean Maps: No persistent expired polygons cluttering the display
5. Consistent Behavior: Matches node-CoT capabilities and ATAK expectations
6. Simplified ETL Logic: No need for complex dual-feature workarounds

Implementation Impact

This enhancement would:

• Enable proper expiring polygon functionality for time-sensitive geospatial data
• Align ETL framework capabilities with underlying node-CoT support
• Solve the persistent polygon problem that affects emergency management systems
• Provide a clean, standards-compliant solution for temporal geospatial features

Conclusion

The underlying node-CoT library already supports polyline shapes, but the ETL framework's feature properties schema artificially limits this capability. Adding polyline support would unlock critical functionality for emergency management and time-sensitive geospatial applications while maintaining full compatibility with existing ATAK systems.

Related to dfpc-coe/CloudTAK#887