Search Icon

    PPL_Min API JavaScript Examples

    PPL_Min API

    Introduction

    The O-Calc Pro PPL_Min API is a lightweight, programmatic interface for building, editing, and exporting O‑Calc Pro pole models. It exposes a consistent element tree (groundline → pole → equipment/assemblies → conductors/spans) driven by a common schema, with methods to set parameters, position components (CoordinateX/A/Z), resolve geometry (ConstrainCoordinates), and serialize models into PPLX files (XML) for analysis or use in O‑Calc Pro. You can construct models from scratch with primitive elements (e.g., PPLWoodPole, PPLCrossArm, PPLInsulator, PPLSpan) or accelerate work by pulling pre‑defined elements/assemblies from a Catalog (.pplc) file using ReferenceCatalog, ensuring standardization and speed.

    JavaScript implementation (PPL_MinJS) runs naturally in Node.js: you require the minified libraries, create a PPLMain with an API key, and manipulate the object model directly. Collections tend to use COM‑style accessors (Children.Count, getItem(i)), coordinates are set in inches for distances and radians for angles, and a simple depth‑first helper (like your Constrain function) applies ConstrainCoordinates("") across the tree before calling SavePoleXml(). Catalog workflows load a Catalog (.pplc) file contents (as XML string) into a ReferenceCatalog and fetch items by Catalog Path/Name (e.g., " NESC Standard\\Ponderosa Pine 45-4"), then place them by setting CoordinateZ (height along the pole) and CoordinateA (around the pole or parent object). coordinates.

    NOTE: The PPL_Min API is a cross-language API that enables the assembly of pole model via the same classes and functions. While the language choice (C#, VB.Net, Python, JavaScript, F#, etc.) mainly affects ecosystem conveniences, the same object model and schema are used, and the modeling logic is the same.

    This document describes two examples of the JavaScript Implementation of this PPL_Min API, namely PPL_MinJS.

     

    Example 1

    Description:

    This JavaScript example demonstrates how to programmatically build an O‑Calc Pro pole model using the PPL_Min API. After loading the required O‑Calc and PPL_Min libraries, it initializes a PPLMain instance with an API key and creates a groundline element to serve as the scene root. The script then constructs a typical wood‑pole assembly by adding a wood pole, an environment (load case), and a crossarm. To populate the structure electrically, it creates an insulator and attaches two spans: the second is cloned from the first, rotated 180° (CoordinateA + Math.PI), and configured with custom geometry and tensioning parameters (span length, end height delta, midspan deflection, and “Sag to Tension”). The insulator is positioned along the crossarm (at CoordinateX = -40), then duplicated three times and distributed across the arm to represent multiple attachment points.

    Beyond the primary pole‑top assembly, the script adds a guying system by creating an anchor and attaching a guy brace, reflecting common structural reinforcement. A recursive Constrain function walks the entire element tree to normalize or resolve coordinates, ensuring all components are properly constrained before export. Finally, the model is serialized to an O‑Calc Pro PPLX XML string via SavePoleXml() and printed to the console. (Tip: avoid embedding real production API keys directly in source; use secure configuration or secret management.)

    Constrain Function:  pElem.ContrainCoordinates(“”);

    The Constrain function walks the entire O‑Calc Pro element tree (groundline → pole → crossarm → insulators → spans → etc.) and calls each element’s ConstrainCoordinates("") method. This is a post‑construction normalization step that resolves each element’s positional/coordinate constraints (e.g., relative offsets, rotations, and attachment rules) into a consistent state prior to saving or analyzing the model. In short, it ensures everything is geometrically “settled” after you’ve programmatically added or modified components.

    Using the Constrain function helps with predictable exports. The produced PPLX XML via the SavePoleXml() function will reflect a fully constrained and valid model, reduce surprises when loading into O-Calc Pro and running calculations.

     

    Example 2

    Description: 

    This example shows how to use the O‑Calc Pro PPL_Min JavaScript API to build a pole model by loading components from an external O‑Calc catalog instead of constructing each element manually. After loading the required libraries, the script reads a .pplc catalog file from disk, loads it into a ReferenceCatalog object, and initializes a new PPLMain instance with the provided API key. Using catalog lookups, the code then assembles a complete pole structure: a Ponderosa Pine 45‑4 wood pole, an NESC loadcase, and a fully pre‑configured crossarm assembly. The crossarm’s elevation is set explicitly (32 ft above groundline), and each catalog item is added into the model’s element tree.

    As in the previous example, the script calls the recursive Constrain function to apply coordinate constraints across the entire element hierarchy, ensuring all components are properly resolved before serialization. Finally, the completed pole model is saved to a PPLX XML string and printed to the console. This example highlights how catalog‑based modeling allows rapid, standardized pole construction using pre‑defined equipment and assemblies.

     

    Coordinates within the O-Calc Model

    In the PPL_Min coordinate system commonly used for O‑Calc Pro pole models:

      • CoordinateZ = vertical coordinate along the pole (elevation). Values are in inches. Note that for items connected to the pole this value is relative to the base of the pole, not the groundline.
      • CoordinateX = is the lateral coordinate along the crossarm or transverse to the pole (for example the insulator positions on a crossarm). Values are in inches.
      • CoordinateA = the relative rotation of the element relative to the parent element. Values are in radians.

    When you assign CoordinateZ on a component attached to the pole, it specifies the height along the pole where that component sits. Because the pole’s local origin is at its base (below the groundline by the setting depth), you add the setting depth to reach a groundline-based height.

     

    The ReferenceCatalog Function

    ReferenceCatalog in the O‑Calc Pro PPL_Min API is the mechanism for working with pre‑defined, reusable components—poles, load cases, crossarm assemblies, equipment, etc.—that are stored in an O‑Calc Pro catalog file (.pplc). Instead of constructing every element from scratch, you load a catalog once and then pull fully‑defined elements (with their default properties, materials, and metadata) directly into your model. This speeds up modeling, ensures standardization based on the end customer’s O-Calc Pro Catalog, and reduces errors.

    The ReferenceCatalog loads in the .pplc Catalog file into memory so that the PPL_Min API can resolve named items, finds the items based on the Catalog folder path and Catalog item name, and returns the fully configured elements/assemblies (a hierarchical of elements) with all the Catalog default.