ArcGIS Pro 3.8 API Reference Guide
ArcGIS.Core.Geometry Namespace / MapPointBuilderEx Class / M Property
Example

In This Topic
    M Property (MapPointBuilderEx)
    In This Topic
    Gets or sets the M-coordinate.
    Syntax
    public double M {get; set;}
    Public Property M As Double
    Remarks
    When the M-value is set, the HasM property is set to true. If this builder is not M-Aware, a default value of NaN is returned.
    Example
    MapPoint Builder Properties
    {
      // MapPointBuilderEx constructors can run on any thread.
    
      MapPoint point1 = null;
      MapPoint point2 = null;
    
      SpatialReference spatialReference = SpatialReferenceBuilder.CreateSpatialReference(54004);
    
      MapPointBuilderEx mapPointBuilder = new MapPointBuilderEx(100, 200, spatialReference);
      SpatialReference sr = mapPointBuilder.SpatialReference; // sr != null
      int wkid = sr.Wkid; // wkid = 54004
      bool hasZ = mapPointBuilder.HasZ;   // hasZ = false
      bool hasM = mapPointBuilder.HasM;   // hasM = false
      bool hasID = mapPointBuilder.HasID; // hasID = false
      bool isEmpty = mapPointBuilder.IsEmpty; // isEmpty = false
      double x = mapPointBuilder.X;   // x = 100
      double y = mapPointBuilder.Y;   // y = 200
      double z = mapPointBuilder.Z;   // z = 0, default value
      double m = mapPointBuilder.M;   // m is NaN, default value
      double id = mapPointBuilder.ID; // id = 0, default value
    
      // Do something with the builder
      mapPointBuilder.Z = 12; // Setting the z-value automatically sets HasZ property to true
    
      point1 = mapPointBuilder.ToGeometry();
      sr = point1.SpatialReference; // sr != null
      wkid = sr.Wkid; // wkid = 54004
      hasZ = point1.HasZ;   // hasZ = true
      hasM = point1.HasM;   // hasM = false
      hasID = point1.HasID; // hasID = false
      x = point1.X;   // x = 100
      y = point1.Y;   // y = 200
      z = point1.Z;   // z = 12
      m = point1.M;   // m is NaN, default value
      id = point1.ID; // id = 0, default value
    
      // Change some of the builder properties
      mapPointBuilder.SetValues(11, 22);
      mapPointBuilder.HasZ = false;
      mapPointBuilder.HasM = true;
      mapPointBuilder.M = 44;
    
      // Create another point
      point2 = mapPointBuilder.ToGeometry();
    
      bool isEqual = point1.IsEqual(point2); // isEqual = false
    
      // Set the builder to empty
      // Sets X and Y to NaN. Sets other attributes to the default values.
      // Does not change the attribute awareness.
      mapPointBuilder.SetEmpty();
    
      MapPoint point3 = mapPointBuilder.ToGeometry();
      sr = point3.SpatialReference; // sr != null
      wkid = sr.Wkid; // wkid = 54004
      hasZ = point3.HasZ;        // hasZ = false
      hasM = point3.HasM;        // hasM = true
      hasID = point3.HasID;      // hasID = false
      isEmpty = point3.IsEmpty;  // isEmpty = true
      x = point3.X;              // x is NaN
      y = point3.Y;              // y is NaN
      z = point3.Z;              // z = 0, default value
      m = point3.M;              // m is NaN, default value
      id = point3.ID;            // ID = 0, default value
    
      // Create a builder from a point
      mapPointBuilder = new MapPointBuilderEx(point2); // point1 = (11, 22, 0, 44, 0)
      sr = mapPointBuilder.SpatialReference; // sr != null
      wkid = sr.Wkid; // wkid = 54004
      hasZ = mapPointBuilder.HasZ;        // hasZ = false
      hasM = mapPointBuilder.HasM;        // hasM = true
      hasID = mapPointBuilder.HasID;      // hasID = false
      isEmpty = mapPointBuilder.IsEmpty;  // isEmpty = false
      x = mapPointBuilder.X;              // x = 11
      y = mapPointBuilder.Y;              // y = 22
      z = mapPointBuilder.Z;              // z = 0, default value
      m = mapPointBuilder.M;              // m = 44
      id = mapPointBuilder.ID;            // ID = 0, default value
    
      // Setting attribute values automatically sets the corresponding flag to true
      mapPointBuilder.Z = 150;
      mapPointBuilder.ID = 2;
    
      // Remove the spatial reference
      mapPointBuilder.SpatialReference = null;
    
      MapPoint point4 = mapPointBuilder.ToGeometry() as MapPoint;
      sr = point3.SpatialReference; // sr = null
      hasZ = point3.HasZ;        // hasZ = true
      hasM = point3.HasM;        // hasM = true
      hasID = point3.HasID;      // hasID = true
      isEmpty = point3.IsEmpty;  // isEmpty = false
      x = point3.X;              // x = 11
      y = point3.Y;              // y = 22
      z = point3.Z;              // z = 150
      m = point3.M;              // m = 44
      id = point3.ID;            // ID = 2
    }
    Calibrate M values using M values from input points - CalibrateByMs
    {
      string json = "{\"hasM\":true,\"paths\":[[[0,0,-1],[1,0,0],[1,1,1],[1,2,2],[3,1,3],[5,3,4],[9,5,5],[7,6,6]]],\"spatialReference\":{\"wkid\":4326}}";
      polyline = PolylineBuilderEx.FromJson(json);
    
      // Interpolate using points (0, 0, 17), (1, 0, 42), (7, 6, 18)
      List<MapPoint> updatePoints = new(3);
      MapPointBuilderEx builder = new(0, 0)
      {
        M = 17
      };
      updatePoints.Add(builder.ToGeometry() as MapPoint);
    
      builder.X = 1;
      builder.M = 42;
      updatePoints.Add(builder.ToGeometry() as MapPoint);
    
      builder.X = 7;
      builder.Y = 6;
      builder.M = 18;
      updatePoints.Add(builder.ToGeometry() as MapPoint);
    
      // Calibrate all the points in the polyline
      double cutOffDistance = polyline.Length;
    
      Polyline updatedPolyline = GeometryEngine.Instance.CalibrateByMs(polyline, updatePoints, UpdateMMethod.Interpolate, cutOffDistance) as Polyline;
      // The points in the updated polyline are
      // (0, 0, 17 ), ( 1, 0, 42 ), ( 1, 1, 38 ), ( 1, 2, 34 ), ( 3, 1, 30 ), ( 5, 3, 26 ), ( 9, 5, 22 ), ( 7, 6, 18 )
    
      // ExtrapolateBefore using points (1, 2, 42), (9, 5, 18)
      builder.X = 1;
      builder.Y = 2;
      builder.M = 42;
      updatePoints[0] = builder.ToGeometry() as MapPoint;
    
      builder.X = 9;
      builder.Y = 5;
      builder.M = 18;
      updatePoints[1] = builder.ToGeometry() as MapPoint;
    
      updatePoints.RemoveAt(2);
    
      updatedPolyline = GeometryEngine.Instance.CalibrateByMs(polyline, updatePoints, UpdateMMethod.ExtrapolateBefore, cutOffDistance) as Polyline;
      // The points in the updated polyline are
      // ( 0, 0, 66 ), ( 1, 0, 58 ), ( 1, 1, 50 ), ( 1, 2, 42 ), ( 3, 1, 3 ), ( 5, 3, 4 ), ( 9, 5, 18 ), ( 7, 6, 6 )
    
      // ExtrapolateAfter using points (0, 0, 17), (1, 2, 42)
      builder.X = 0;
      builder.Y = 0;
      builder.M = 17;
      updatePoints.Insert(0, builder.ToGeometry() as MapPoint);
    
      updatePoints.RemoveAt(2);
    
      updatedPolyline = GeometryEngine.Instance.CalibrateByMs(polyline, updatePoints, UpdateMMethod.ExtrapolateAfter, cutOffDistance) as Polyline;
      // The points in the updated polyline are
      // ( 0, 0, 17 ), ( 1, 0, 0 ), ( 1, 1, 1 ), ( 1, 2, 42 ), ( 3, 1, 50.333333333333333 ), ( 5, 3, 58.666666666666671 ), ( 9, 5, 67 ), ( 7, 6, 75.333333333333343 )
    
      // ExtrapolateAfter and Interpolate using points (0, 0, 17), (1, 2, 42)
      updatedPolyline = GeometryEngine.Instance.CalibrateByMs(polyline, updatePoints, UpdateMMethod.ExtrapolateAfter | UpdateMMethod.Interpolate, cutOffDistance) as Polyline;
      // The points in the updated polyline are
      // (0,0,17),(1,0,25.333333333333336),(1,1,33.666666666666671),(1,2,42),(3,1,50.333333333333336),(5,3,58.666666666666671),(9,5,67),(7,6,75.333333333333343)
    }
    Calibrate M-values using segment lengths and M values from input points - CalibrateMsByDistance
    {
      List<MapPoint> points = [];
    
      MapPointBuilderEx pointBuilder = new(0, 0)
      {
        HasM = true,
        M = 0
      };
      points.Add(pointBuilder.ToGeometry());
    
      pointBuilder.SetValues(0, 8);
      pointBuilder.M = 12;
      points.Add(pointBuilder.ToGeometry());
    
      pointBuilder.SetValues(0, 18);
      pointBuilder.M = 10;
      points.Add(pointBuilder.ToGeometry());
    
      pointBuilder.SetValues(0, 28);
      pointBuilder.M = 14;
      points.Add(pointBuilder.ToGeometry());
    
      pointBuilder.SetValues(0, 32);
      pointBuilder.M = 20;
      points.Add(pointBuilder.ToGeometry());
    
      pointBuilder.SetValues(0, 38);
      pointBuilder.M = 26;
      points.Add(pointBuilder.ToGeometry());
    
      pointBuilder.SetValues(0, 50);
      pointBuilder.M = 30;
      points.Add(pointBuilder.ToGeometry());
    
      polyline = PolylineBuilderEx.CreatePolyline(points, AttributeFlags.HasM);
      // The points in the polyline are (0, 0, 0), (0, 8, 12), (0, 18, 10), (0, 28, 14), (0, 32, 20), (0, 38, 26), (0, 50, 30)
    
      // Calibrate Ms using points (0, 8, 15), (0, 28, 30), (0, 38, 20)
      points.Clear();
      pointBuilder.SetValues(0, 8);
      pointBuilder.M = 15;
      points.Add(pointBuilder.ToGeometry());
    
      pointBuilder.SetValues(0, 28);
      pointBuilder.M = 30;
      points.Add(pointBuilder.ToGeometry());
    
      pointBuilder.SetValues(0, 38);
      pointBuilder.M = 20;
      points.Add(pointBuilder.ToGeometry());
    
      double cutOffDistance = polyline.Length;
    
      // ExtrapolateBefore
      Polyline updatedPolyline = GeometryEngine.Instance.CalibrateMsByDistance(polyline, points, UpdateMMethod.ExtrapolateBefore, true, cutOffDistance) as Polyline;
      // The points in the updated polyline are
      // (0, 0, 9), (0, 8, 15), (0, 18, 10), (0, 28, 30), (0, 32, 20), (0, 38, 20), (0, 50, 30)
    
      // Interpolate
      updatedPolyline = GeometryEngine.Instance.CalibrateMsByDistance(polyline, points, UpdateMMethod.Interpolate, true, cutOffDistance) as Polyline;
      // The points in the updated polyline are
      // (0, 0, 0), (0, 8, 15), (0, 18, 22.5), (0, 28, 30), (0, 32, 26), (0, 38, 20), (0, 50, 30)
    
      // ExtrapolateAfter
      updatedPolyline = GeometryEngine.Instance.CalibrateMsByDistance(polyline, points, UpdateMMethod.ExtrapolateAfter, true, cutOffDistance) as Polyline;
      // The points in the updated polyline are
      // (0, 0, 0), (0, 8, 15), (0, 18, 10), (0, 28, 30), (0, 32, 20), (0, 38, 20), (0, 50, 8)
    
      // ExtrapolateBefore and Interpolate and ExtrapolateAfter
      updatedPolyline = GeometryEngine.Instance.CalibrateMsByDistance(polyline, points, UpdateMMethod.ExtrapolateAfter, true, cutOffDistance) as Polyline;
      // The points in the updated polyline are
      // (0, 0, 9), (0, 8, 15), (0, 18, 22.5), (0, 28, 30), (0, 32, 26), (0, 38, 20), (0, 50, 8)
    }
    Add an offset value to each of the M-values - OffsetMs
    {
      // Create a polyline and add an offset of 2 to each of the M-values
      MapPointBuilderEx pointBuilder = new(0, 0)
      {
        M = 1
      };
      MapPoint point1 = pointBuilder.ToGeometry();
    
      pointBuilder.SetValues(2, 2);
      pointBuilder.M = 3;
      MapPoint point2 = pointBuilder.ToGeometry();
    
      polyline = PolylineBuilderEx.CreatePolyline([point1, point2], AttributeFlags.HasM);
      ;
    
      Polyline outPolyline = GeometryEngine.Instance.OffsetMs(polyline, 2) as Polyline;
      // The xy-values of the points in outPolyline are the same as the points in the input polyline.
      // The M-values in outPolyline are { 3, 5 }
    
      // Create an envelope and add an offset of 25 to each of the M-values
      EnvelopeBuilderEx envelopeBuilder = new(-5, 1, 2, 4)
      {
        MMin = 10,
        MMax = 20
      };
      Envelope envelope = envelopeBuilder.ToGeometry();
    
      Envelope outEnvelope = GeometryEngine.Instance.OffsetMs(envelope, 25) as Envelope;
      // The xy-values of the points in outEnvelope are the same as the points in the input envelope.
      // outEnvelope.MMin = 35, outEnvelope.MMax = 45
    
      // Add a negative offset to the M-values of the envelope
      outEnvelope = GeometryEngine.Instance.OffsetMs(envelope, -10) as Envelope;
      // The xy-values of the points in outEnvelope are the same as the points in the input envelope.
      // outEnvelope.MMin = 0, outEnvelope.MMax = 10
    }
    Snap the M-values to the M-precision of the spatial reference - SnapMsToSpatialReference
    {
      SpatialReference sr = SpatialReferences.WebMercator;  // precision = 1 / MScale = 0.0001
    
      // MapPoint
      MapPointBuilderEx pointBuilder = new(3, 4, sr)
      {
        M = 5.00006
      };
      MapPoint point = pointBuilder.ToGeometry();
      MapPoint outputPoint = GeometryEngine.Instance.SnapMsToSpatialReference(point) as MapPoint;
      // outputPoint.M = 5.0001
    
      // Multipoint
      MapPointBuilderEx mapPointBuilderEx = new(-3, -4, sr)
      {
        M = -5.000007
      };
      pointBuilder = mapPointBuilderEx;
      MapPoint point2 = pointBuilder.ToGeometry();
      Multipoint multipoint = MultipointBuilderEx.CreateMultipoint([point, point2], AttributeFlags.HasM, sr);
      Multipoint outputMultipoint = GeometryEngine.Instance.SnapMsToSpatialReference(multipoint) as Multipoint;
      // outputMultipoint.Points[0].M = 5.0001, outputMultipoint.Points[1].M = -5
    
      // Polyline
      string json = "{\"hasM\":true,\"paths\":[[[3,2,10.00065],[3,4,15.000325],[5,4,20],[5,2,15.000325],[3,2,10.00065]]],\"spatialReference\":{\"wkid\":3857}}";
      polyline = PolylineBuilderEx.FromJson(json);
      Polyline outputPolyline = GeometryEngine.Instance.SnapMsToSpatialReference(polyline) as Polyline;
      // The M-values for the vertices in outputPolyline are { 10.0007, 15.0003, 20, 15.0003, 10.0007 }
    }
    Requirements

    Target Platforms: Windows 11 Home, Pro, Enterprise (64 bit)

    ArcGIS Pro version: 3.0 or higher.
    See Also