📢 Call for Feedback: Optimizing Model Derivative Extraction for 3D Polylines

At Autodesk, we're constantly working to enhance the performance and efficiency of Autodesk Platform Services (APS), including the Model Derivative API. We're implementing a significant optimization for how 3D Polylines (3DPOLY /AcDb3dPolyline) from DWG source files are processed.

This change focuses on reducing unnecessary data bloat and improving responsiveness, particularly within the Autodesk Construction Cloud (ACC) property browser and for API consumers.

The Change: Discontinuing Vertex Handle Extraction

We will discontinue the extraction of individual Vertex Handle properties into the Model Derivative's Property Database (properties.db).

Why?

When a DWG containing 3D Polylines is processed, every single vertex generates its own "Handle" entry in the Property Database. A polyline with 1,000 vertices creates 1,000 redundant metadata entries like "Vertex - 1: Handle: <ID>", "Vertex - 2: Handle: <ID>", etc.

This "property bloat" significantly degrades performance during metadata indexing and querying.

Real-world example:

A test drawing containing a single 3D Polyline with 6 vertices generates 19 total properties. After removing the 6 vertex handle entries, the property counts drop to 13 properties - a 31.6% reduction. For models with hundreds or thousands of polylines with many vertices each, this optimization delivers substantial performance improvements.

Impacted Model Derivative API Endpoints

The following API endpoints will no longer return vertex handle properties for 3D Polylines:

🔴 Direct Impact: API response structure changes
🟡 Indirect Impact: Methods that rely on property database but may not explicitly show vertex handles

Example: API Response Changes

Here's what the Model Derivative API response looks like before and after this change:

❌ Current Response (GET /properties)

{
  "data": {
    "collection": [
      {
        "objectid": 134,
        "name": "Polyline [2C1]",
        "properties": {
          "General": {
            "Handle": "2c1",
            "Layer": "0",
            "Vertex - 1: Handle": "2c3",  ← REMOVED
            "Vertex - 2: Handle": "2c4",  ← REMOVED
            "Vertex - 3: Handle": "2c5",  ← REMOVED
            "Name": "3D Polyline"
          },
          "Geometry": {
            "Length": "3765.836 mm"
          }
        }
      }
    ]
  }
}

✅ New Response (Optimized)

{
  "data": {
    "collection": [
      {
        "objectid": 134,
        "name": "Polyline [2C1]",
        "properties": {
          "General": {
            "Handle": "2c1",           ← RETAINED
            "Layer": "0",              ← RETAINED
            "Name": "3D Polyline"      ← RETAINED
          },
          "Geometry": {
            "Length": "3765.836 mm"    ← RETAINED
          }
        }
      }
    ]
  }
}

Result: This specific 3D Polyline had 6 vertices generating 6 vertex handle properties. Removing these reduces the property count from 19 to 13 (31.6% reduction). For complex models with polylines containing hundreds of vertices, the performance improvement compounds significantly.

Example API Usage (Node.js)

If you're using the Model Derivative API directly, here's how your code might be affected:

⚠️ IMPACTED: Querying Property Database with GET /properties

// ❌ This code will break - vertex handles won't exist
const response = await axios.get(
  `https://developer.api.autodesk.com/modelderivative/v2/designdata/${urn}/metadata/${guid}/properties`,
  { headers: { Authorization: `Bearer ${token}` } }
);

const props = response.data.data.collection[0].properties.General;

// These properties will no longer exist:
console.log(props["Vertex - 1: Handle"]); // undefined
console.log(props["Vertex - 2: Handle"]); // undefined

⚠️ IMPACTED: Using POST /properties:query

// ❌ Query results won't include vertex handles
const response = await axios.post(
  `https://developer.api.autodesk.com/modelderivative/v2/designdata/${urn}/metadata/${guid}/properties:query`,
  {
    fields: ["objectid", "name", "properties"],
    query: { "$in": ["objectid", 134] }  // Query for object with ID 134
  },
  { headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" } }
);

const props = response.data.data.collection[0].properties.General;

// Vertex handles no longer in query results:
console.log(props["Vertex - 1: Handle"]); // undefined (was "2c3" before)
console.log(props["Vertex - 2: Handle"]); // undefined (was "2c4" before)

// ❌ Can't filter by vertex handles either
const badQuery = {
  query: { "$eq": ["properties.General['Vertex - 1: Handle']", "2c3"] }
};
// This query will return no results after the change

✅ SAFE: Properties That Remain

// ✅ These properties continue to work
const response = await axios.get(
  `https://developer.api.autodesk.com/modelderivative/v2/designdata/${urn}/metadata/${guid}/properties`,
  { headers: { Authorization: `Bearer ${token}` } }
);

const props = response.data.data.collection[0].properties;

// All other properties remain available:
console.log(props.General["Handle"]);     // ✓ Still works
console.log(props.General["Layer"]);      // ✓ Still works
console.log(props.Geometry["Length"]);    // ✓ Still works

Are You Affected? Two Workflows Explained

✅ Workflow A: Accessing Geometry through the Viewer (SAFE)

This workflow is NOT impacted.

Most developers extract 3D Polyline coordinates directly from the APS Viewer's fragment geometry (the raw render buffers). This method operates on the highly optimized data the GPU uses for rendering.

// Best Practice: Accessing coordinates via Viewer Geometry API
function get3DPolylineCoordinates(viewer, dbId) {
    const model = viewer.model;
    const instanceTree = model.getInstanceTree();

    instanceTree.enumNodeFragments(dbId, (fragId) => {
        const renderProxy = viewer.impl.getRenderProxy(model, fragId);
        const geometry = renderProxy.geometry;
        const matrix = renderProxy.matrixWorld; // World transform

        // Direct access to vertex buffer
        const positions = geometry.vb;
        const stride = geometry.vbstride || 3; 

        for (let i = 0; i < positions.length; i += stride) {
            let point = new THREE.Vector3(
                positions[i],     // X
                positions[i + 1], // Y
                positions[i + 2]  // Z
            );
            point.applyMatrix4(matrix); // Apply world transform
            console.log(`Point: x: ${point.x.toFixed(3)}, y: ${point.y.toFixed(3)}, z: ${point.z.toFixed(3)}`);
        }
    });
}

If your application uses this approach, you will experience NO disruption. The 3D Polyline will continue to render correctly, and its spatial data remains fully accessible through the geometry buffers.

⚠️ Workflow B: Querying Vertex Handles from Property Database (IMPACTED)

This workflow WILL be impacted.

If your application explicitly queries the Model Derivative's Property Database (via GET /properties, POST /properties:query, or model.getProperties()) to find specific Vertex - N: Handle entries, these properties will no longer be available.

// ⚠️ THIS CODE WILL BREAK
model.getProperties(dbId, (result) => {
    result.properties.forEach(prop => {
        if (prop.displayName.startsWith("Vertex -") && 
            prop.displayName.endsWith(": Handle")) {
            
            // This property will no longer exist after the change!
            storeVertexHandle(prop.displayValue);
        }
    });
});

If your custom automation, QA tooling, or external database links rely on parsing these specific Vertex - N: Handle entries for 3D Polylines, your integration will need to be updated to use the Viewer Geometry API instead.

What is NOT Changing

• 3D Polyline Rendering: Your 3D Polylines will continue to appear correctly in the APS Viewer.
• Vertex Coordinates: Accessible via Viewer's geometry buffers (the recommended approach).
• Other Properties: General attributes (Layer, Color, Linetype, entity Handle) and Geometry totals (Length) remain fully extracted.
• 2D Polyline Vertex Properties: Vertex-specific properties for 2D Polylines (e.g., segment widths) are unaffected.

We Need Your Feedback!

As a Software-as-a-Service (SaaS) product, changes to APS are deployed globally. It's critical that we understand any potential downstream effects.

If your application relies on Vertex - N: Handle properties extracted from the Model Derivative's Property Database via the /properties or /properties:query endpoints, please reach out to us immediately. Share your specific use case with the APS Developer Support Team. Your feedback is crucial to ensuring a smooth transition for all developers.

References

• Model Derivative API - GET Properties Documentation
• How to get coordinates/vertices from an object - Stack Overflow
• Show Mesh Triangles from HitTest Data | APS Blog