Work with utility elements | ArcGIS Maps SDK for Flutter

An array of analysisAnalysis is a systematic examination of a problem that provides new information.Learn more and tracing options usually begin with or include a utility elementA utility element is an entity in a utility network that corresponds to a feature or a part of a feature (for example, a terminal inside a device).Learn more in the result. This element corresponds to a network featureA feature is a single record, also known as a row, that represents a real-world entity. It typically contains a geometry (point, multipoint, polyline, or polygon) and attributes but it can also contain just attributes.Learn more or object that contains additional information such as a terminalA terminal represents logical ports, entries, or exit locations on a single device or junction object within a utility network. Each port can flow in or out. Each device can contain many terminals, all of which can be interconnected.Learn more or fraction along value that affects the analysis. For example, the utility element's terminal may limit the number of connectivity associationsAn association is a relationship between two elements that is reflected in a utility network topology.Learn more or change the direction of a traceA trace is an action that analyzes the paths in a utility network and returns features based on connectivity or traversability from the specified starting points.Learn more, while its fraction along value may return a partial geometryA geometry is a geometric shape, such as a point, polyline, or polygon, that contains one or more coordinates and a spatial reference.Learn more from a trace.

This utility element may be created from a feature or asset typeAn asset type is a class that refines a utility element's classification within an asset group. For example, a power transformer is an asset type of the transformer asset group within an electric device network.Learn more with a global id. The feature may be a result of a query or identifyIdentify is a query based on a point on a map or scene that is used to find feature, graphic, or raster cell data.Learn more operation on a layerA layer is a reference to a collection of geographic data that is used to access and display data. The data for layers are typically provided by the basemap layer service and data services.Learn more or tableA table is a non-spatial dataset in a feature service. All records in a table share the same set of fields.Learn more that is part of the utility networkA utility network is a feature service that represents a utility system, such as water, gas, or electricity. A utility network provides the capabilities to visualize, edit, and analyze utility assets and data.Learn more.

Utility element from a feature

You may query for a specific feature using any of its fields or geometry or interactively identify a feature in a map viewA map view is a user interface that displays map layers and graphics in 2D. It controls the area (extent) of the map that is visible and supports user interactions such as pan and zoom.Learn more. When using identifyIdentify is a query based on a point on a map or scene that is used to find feature, graphic, or raster cell data.Learn more, the feature may be found in the GeoElement list immediately under IdentifyLayerResult when part of a FeatureLayer or from sublayerResults when part of a SubtypeFeatureLayer.

Use dark colors for code blocksCopy
    final query = QueryParameters()
      ..whereClause = "GlobalId like '{D353C10C-E617-4618-BDD0-B48EDB822D07}'";
    final queryResult = await table.queryFeatures(query);

    if (queryResult.features().isEmpty) return;
    final feature = queryResult.features().first as ArcGISFeature;

Use dark colors for code blocksCopy
    final identifyLayerResults = await _mapViewController.identifyLayers(
      screenPoint: position,
      tolerance: 5,
      returnPopupsOnly: false,
    );

    ArcGISFeature? sublayerFeature;
    ArcGISFeature? feature;

    for (final layerResult in identifyLayerResults) {
      if (layerResult.layerContent is SubtypeFeatureLayer) {
        for (final subLayerResult in layerResult.sublayerResults) {
          for (final geoElement in subLayerResult.geoElements) {
            sublayerFeature = geoElement as ArcGISFeature;
          }
        }
      } else if (layerResult.layerContent is FeatureLayer) {
        for (final geoElement in layerResult.geoElements) {
          feature = geoElement as ArcGISFeature;
        }
      }
    }

Use dark colors for code blocksCopy
    await feature.load();
    final element = _utilityNetwork.createElement(arcGISFeature: feature);

Utility element from an asset type

An asset typeAn asset type is a class that refines a utility element's classification within an asset group. For example, a power transformer is an asset type of the transformer asset group within an electric device network.Learn more can come from another utility elementA utility element is an entity in a utility network that corresponds to a feature or a part of a feature (for example, a terminal inside a device).Learn more or be derived from a feature in the utility network, except from a subnet line table that does not have an asset type. You can use the feature's table name to get its network sourceA network source is a feature table whose features comprise one of a utility network's datasets.Learn more. Use the network source and the feature's subtype to get its asset groupAn asset group is the main classification of a utility element. Each asset group is then divided into a collection of asset types.Learn more. From the asset group, you can select an asset type by name or code.

Use dark colors for code blocksCopy
    var assetType = otherElement.assetType;
    var element = _utilityNetwork.createElementWithAssetType(
      assetType,
      globalId: globalId,
    );

    final tableName = feature.featureTable?.tableName;
    if (tableName == null) return;
    var networkSource = _utilityNetwork.definition?.getNetworkSource(tableName);

    final subtypeName = feature.getFeatureSubtype()?.name;
    if (subtypeName == null) return;
    var assetGroup = networkSource?.getAssetGroup(subtypeName);
    if (assetGroup == null) return;

    final assetTypeCode = feature.attributes['ASSETTYPE'] as int;
    assetType =
        assetGroup.assetTypes.firstWhere((t) => t.code == assetTypeCode);

    networkSource = _utilityNetwork.definition
        ?.getNetworkSource('Electric Distribution Device');
    assetGroup = networkSource?.getAssetGroup('Service Point');

    assetType =
        assetGroup?.getAssetType('Single Phase Low Voltage Meter') ?? assetType;
    element = _utilityNetwork.createElementWithAssetType(
      assetType,
      globalId: globalId,
    );

Utility element properties

A terminal is required when a UtilityElement that supports more than one terminalA terminal represents logical ports, entries, or exit locations on a single device or junction object within a utility network. Each port can flow in or out. Each device can contain many terminals, all of which can be interconnected.Learn more is used in a trace and optional when used to get associationsAn association is a relationship between two elements that is reflected in a utility network topology.Learn more. Terminals impact tracesA trace is an action that analyzes the paths in a utility network and returns features based on connectivity or traversability from the specified starting points.Learn more and connectivity associations.

Use dark colors for code blocksCopy
    if (element.assetType.terminalConfiguration!.terminals.isNotEmpty) {
      element.terminal =
          element.assetType.terminalConfiguration!.terminals.first;
    }

If the featureA feature is a single record, also known as a row, that represents a real-world entity. It typically contains a geometry (point, multipoint, polyline, or polygon) and attributes but it can also contain just attributes.Learn more represents a line, you can optionally specify a location along the line to use as a trace location. This value is a percentage of the length of the line, beginning from the line's 'from' point.

Use UtilityElement.fractionAlongEdge to define the location of the point along the line.

The following example uses the GeometryEngine to get the fraction of a tap location along the line.

Use dark colors for code blocksCopy
    if (element.networkSource?.sourceType == UtilityNetworkSourceType.edge &&
        feature.geometry is Polyline) {
      var line = feature.geometry as Polyline;
      if (line.hasZ) {
        final line2 = GeometryEngine.removeZ(line) as Polyline?;
        if (line2 != null) line = line2;
      }
      if (mapPoint.spatialReference != null &&
          line.spatialReference != mapPoint.spatialReference) {
        final projectedLine = GeometryEngine.project(
          line,
          outputSpatialReference: mapPoint.spatialReference!,
        ) as Polyline?;
        if (projectedLine != null) line = projectedLine;
      }
      final percentAlong = GeometryEngine.fractionAlong(
        line: line,
        point: mapPoint,
        tolerance: double.nan,
      );
      if (!percentAlong.isNaN) {
        element.fractionAlongEdge = percentAlong;
      }
    }