第22章 - 扩展开发与自定义函数

package com.example.jtsext;

import java.util.ArrayList;
import java.util.List;

import org.locationtech.jts.geom.Coordinate;
import org.locationtech.jts.geom.Geometry;
import org.locationtech.jts.geom.GeometryFactory;
import org.locationtech.jts.geom.LineString;

/**
 * Splits a LineString where the deflection angle exceeds a threshold.
 */
public class SplitFunctions {

  public static Geometry splitByAngle(Geometry geom, double maxAngleDeg) {
    if (!(geom instanceof LineString)) return geom;
    LineString line = (LineString) geom;
    GeometryFactory fact = line.getFactory();
    Coordinate[] pts = line.getCoordinates();
    List<LineString> parts = new ArrayList<LineString>();
    int start = 0;
    for (int i = 1; i < pts.length - 1; i++) {
      double angle = deflection(pts[i - 1], pts[i], pts[i + 1]);
      if (angle > maxAngleDeg) {
        parts.add(makeLine(fact, pts, start, i));
        start = i;
      }
    }
    parts.add(makeLine(fact, pts, start, pts.length - 1));
    return fact.buildGeometry(parts);
  }

  private static double deflection(Coordinate a, Coordinate b, Coordinate c) {
    double v1x = b.x - a.x, v1y = b.y - a.y;
    double v2x = c.x - b.x, v2y = c.y - b.y;
    double cross = v1x * v2y - v1y * v2x;
    double dot = v1x * v2x + v1y * v2y;
    return Math.toDegrees(Math.abs(Math.atan2(cross, dot)));
  }

  private static LineString makeLine(GeometryFactory fact, Coordinate[] pts, int from, int to) {
    Coordinate[] sub = new Coordinate[to - from + 1];
    System.arraycopy(pts, from, sub, 0, sub.length);
    return fact.createLineString(sub);
  }

  private SplitFunctions() {
  }
}

// modules/tests/src/main/java/org/locationtech/jtstest/geomfunction/GeometryFunction.java
public interface GeometryFunction {
  String getCategory();
  String getName();
  String getDescription();
  String[] getParameterNames();
  Class<?>[] getParameterTypes();
  Class<?> getReturnType();
  String getSignature();
  Object invoke(Geometry geom, Object[] args);
  boolean equals(Object obj);
  boolean isBinary();
  boolean isRequiredB();
}

// 添加一个类里的全部 public static 几何函数
public void add(Class<?> geomFuncClass);

// 按类名加载（会走 Class.forName，可加载 classpath 上任意位置的类）
public void add(String geomFuncClassname) throws ClassNotFoundException;

// 添加单个函数对象（自定义 GeometryFunction 时用）
public void add(GeometryFunction func);

// 查找
public GeometryFunction find(String name);
public GeometryFunction find(String name, int argCount);
public GeometryFunction find(String category, String name);

public static GeometryFunctionRegistry createTestBuilderRegistry() {
  GeometryFunctionRegistry funcRegistry = new GeometryFunctionRegistry();

  funcRegistry.add(GeometryFunctions.class);
  funcRegistry.add(BoundaryFunctions.class);
  funcRegistry.add(BufferFunctions.class);
  // …… 约 50 个类
  funcRegistry.add(OverlayNGFunctions.class);
  funcRegistry.add(OverlayNGRobustFunctions.class);
  funcRegistry.add(TriangulationFunctions.class);
  funcRegistry.add(ValidationFunctions.class);
  funcRegistry.add(WriterFunctions.class);

  return funcRegistry;
}

package com.example.jtsext;

import org.locationtech.jts.geom.Geometry;
import org.locationtech.jts.geom.GeometryFactory;
import org.locationtech.jts.geom.PrecisionModel;
import org.locationtech.jts.geom.util.GeometryFixer;
import org.locationtech.jts.geom.util.GeometryTransformer;
import org.locationtech.jts.precision.GeometryPrecisionReducer;
import org.locationtech.jtstest.geomfunction.Metadata;

/**
 * TestBuilder 函数：栅格吸附与吸附后修复。
 * <p>
 * 注册方式：{@code java -jar JTSTestBuilder.jar -geomfunc com.example.jtsext.SnapFunctions}
 */
public class SnapFunctions {

  /**
   * 把几何坐标吸附到指定大小的网格，必要时修复产生的非法几何。
   *
   * @param geom     输入几何
   * @param gridSize 网格边长，必须为正数
   * @return 吸附（并按需修复）后的几何
   */
  public static Geometry snapToGrid(Geometry geom, double gridSize) {
    if (geom == null || geom.isEmpty()) return geom;
    if (gridSize <= 0) {
      throw new IllegalArgumentException("gridSize must be positive: " + gridSize);
    }
    PrecisionModel pm = new PrecisionModel(1.0 / gridSize);
    Geometry snapped = GeometryPrecisionReducer.reduce(geom, pm);
    if (!snapped.isValid()) {
      snapped = GeometryFixer.fix(snapped);
    }
    return snapped;
  }

  /**
   * 只做吸附，不做有效性修复（用于对比研究）。
   *
   * @param geom     输入几何
   * @param gridSize 网格边长
   * @return 吸附结果，可能非法
   */
  public static Geometry snapOnly(Geometry geom, double gridSize) {
    if (geom == null || geom.isEmpty()) return geom;
    PrecisionModel pm = new PrecisionModel(1.0 / gridSize);
    return GeometryPrecisionReducer.reduce(geom, pm);
  }

  /**
   * 统计几何中被修复的“非法片段”数量。
   * 判据：吸附前后顶点数变化 + 结果是否为 Multi 类型。
   *
   * @param geom     输入几何
   * @param gridSize 网格边长
   * @return 0 表示无需修复，大于 0 表示吸附后产生了非法几何
   */
  public static int snapRepairCount(Geometry geom, double gridSize) {
    if (geom == null || geom.isEmpty()) return 0;
    Geometry snapped = snapOnly(geom, gridSize);
    return snapped.isValid() ? 0 : 1;
  }

  /**
   * 用 Transformer 删除所有内环（洞）。
   * 演示结构级扩展：只改写 Polygon，其它类型原样返回。
   *
   * @param geom 输入几何
   * @return 去洞后的几何
   */
  public static Geometry removeHoles(Geometry geom) {
    return new HoleRemovingTransformer().transform(geom);
  }

  private SnapFunctions() {
  }

  /**
   * 把每个 Polygon 的内环全部去掉，保留外环。
   */
  private static class HoleRemovingTransformer extends GeometryTransformer {

    @Override
    protected Geometry transformPolygon(org.locationtech.jts.geom.Polygon geom, Geometry parent) {
      if (geom.getNumInteriorRing() == 0) return super.transformPolygon(geom, parent);
      return factory.createPolygon((org.locationtech.jts.geom.LinearRing) transform(geom.getExteriorRing()));
    }
  }
}

package com.example.jtsext;

import org.junit.Test;
import org.locationtech.jts.geom.Geometry;
import org.locationtech.jts.io.WKTReader;

import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertFalse;
import static org.junit.Assert.assertTrue;

public class SnapFunctionsTest {

  private final WKTReader reader = new WKTReader();

  @Test
  public void snapToGrid_roundsCoordinates() throws Exception {
    Geometry in = reader.read("POLYGON ((0.1 0.1, 9.9 0.1, 9.9 9.9, 0.1 9.9, 0.1 0.1))");
    Geometry out = SnapFunctions.snapToGrid(in, 1.0);
    assertTrue(out.isValid());
    assertEquals(100.0, out.getArea(), 1e-9);
  }

  @Test
  public void snapToGrid_rejectsNonPositiveGrid() throws Exception {
    Geometry in = reader.read("POINT (0 0)");
    try {
      SnapFunctions.snapToGrid(in, 0);
      throw new AssertionError("expected IllegalArgumentException");
    } catch (IllegalArgumentException expected) {
      assertTrue(expected.getMessage().contains("gridSize"));
    }
  }

  @Test
  public void removeHoles_dropsAllInteriorRings() throws Exception {
    Geometry in = reader.read(
        "POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0), (2 2, 4 2, 4 4, 2 4, 2 2))");
    Geometry out = SnapFunctions.removeHoles(in);
    assertEquals(1, out.getNumGeometries());
    assertEquals(0, ((org.locationtech.jts.geom.Polygon) out).getNumInteriorRing());
    assertEquals(in.getArea() + 4.0, out.getArea(), 1e-9);
  }

  @Test
  public void snapRepairCount_zeroWhenAlreadyValid() throws Exception {
    Geometry in = reader.read("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))");
    assertEquals(0, SnapFunctions.snapRepairCount(in, 1.0));
  }

  @Test
  public void emptyInput_returnsEmpty() throws Exception {
    Geometry in = reader.read("POLYGON EMPTY");
    Geometry out = SnapFunctions.snapToGrid(in, 1.0);
    assertTrue(out.isEmpty());
    assertFalse(out.isValid() == false);
  }
}

// modules/tests/src/main/java/org/locationtech/jtstest/geomfunction/Metadata.java
@Retention(RetentionPolicy.RUNTIME)
public @interface Metadata {
  String name() default "";
  String title() default "";
  String description() default "";
  boolean isRequired() default true;
}

// 无注解：显示为 "buffer(Geometry,double) -> Geometry"，参数名 Arg 0
public static Geometry bufferPlain(Geometry g, double distance) {
  return g.buffer(distance);
}

// 有注解：显示为 "bufferAnnotated(Geometry,Distance) -> Geometry"，并有说明
@Metadata(description = "Buffers a geometry by the given distance")
public static Geometry bufferAnnotated(
    Geometry g,
    @Metadata(title = "Distance", description = "Buffer distance in CRS units")
    double distance) {
  return g.buffer(distance);
}

public static Geometry unionOrSelf(
    Geometry a,
    @Metadata(isRequired = false) Geometry b) {
  if (b == null) return a.union();
  return a.union(b);
}

public static Geometry bufferWithStyle(Geometry g, double distance, String joinStyle) {
  BufferParameters params = new BufferParameters();
  if ("mitre".equalsIgnoreCase(joinStyle)) {
    params.setJoinStyle(BufferParameters.JOIN_MITRE);
  }
  else if ("bevel".equalsIgnoreCase(joinStyle)) {
    params.setJoinStyle(BufferParameters.JOIN_BEVEL);
  }
  else {
    params.setJoinStyle(BufferParameters.JOIN_ROUND);
  }
  return BufferOp.bufferOp(g, distance, params);
}

// modules/tests/src/main/java/org/locationtech/jtstest/geomop/GeometryOperation.java
public interface GeometryOperation {
  Class getReturnType(String opName);
  Result invoke(String opName, Geometry geometry, Object[] args) throws Exception;
}

public class LoggingGeometryOperation implements GeometryOperation {
  private GeometryOperation geomOp = new GeometryMethodOperation();

  public LoggingGeometryOperation() {
  }

  public LoggingGeometryOperation(GeometryOperation geomOp) {
    this.geomOp = geomOp;
  }

  public Class getReturnType(String opName) {
    return GeometryMethodOperation.getGeometryReturnType(opName);
  }

  public Result invoke(String opName, Geometry geometry, Object[] args) throws Exception {
    System.out.println("Operation <" + opName + ">");
    System.out.println("Geometry: " + geometry);
    for (int i = 0; i < args.length; i++) {
      System.out.println("Arg[" + i + "]: " + args[i]);
    }
    Result result = geomOp.invoke(opName, geometry, args);
    System.out.println("Result==> " + result.toFormattedString());
    return result;
  }
}

package com.example.jtsext;

import java.util.LinkedHashMap;
import java.util.Map;

import org.locationtech.jts.geom.Geometry;
import org.locationtech.jts.geom.TopologyException;
import org.locationtech.jtstest.geomop.GeometryFunctionOperation;
import org.locationtech.jtstest.geomop.GeometryOperation;
import org.locationtech.jtstest.testrunner.Result;

/**
 * 包装一个 GeometryOperation，统计耗时并在拓扑异常时降级重试。
 */
public class TimingOperation implements GeometryOperation {

  private final GeometryOperation delegate;
  private final Map<String, long[]> stats = new LinkedHashMap<String, long[]>();

  public TimingOperation(GeometryOperation delegate) {
    this.delegate = delegate;
  }

  public Class getReturnType(String opName) {
    return delegate.getReturnType(opName);
  }

  public Result invoke(String opName, Geometry geometry, Object[] args) throws Exception {
    long start = System.nanoTime();
    boolean degraded = false;
    try {
      return delegate.invoke(opName, geometry, args);
    } catch (TopologyException e) {
      degraded = true;
      throw e;
    } finally {
      long elapsed = System.nanoTime() - start;
      long[] slot = stats.get(opName);
      if (slot == null) {
        slot = new long[3];
        stats.put(opName, slot);
      }
      slot[0] += 1;              // 调用次数
      slot[1] += elapsed;        // 总耗时（纳秒）
      slot[2] += degraded ? 1 : 0;
    }
  }

  public Map<String, long[]> getStats() {
    return stats;
  }

  public static TimingOperation wrapDefault() {
    return new TimingOperation(new GeometryFunctionOperation());
  }
}

GeometryFunctionRegistry registry = GeometryFunctionRegistry.createTestBuilderRegistry();
registry.add("com.example.jtsext.SnapFunctions");
TimingOperation op = new TimingOperation(new GeometryFunctionOperation(registry));

public class GeometryTransformer {
  protected GeometryFactory factory = null;

  public final Geometry transform(Geometry inputGeom) {
    this.inputGeom = inputGeom;
    this.factory = inputGeom.getFactory();
    if (inputGeom instanceof Point)          return transformPoint((Point) inputGeom, null);
    if (inputGeom instanceof MultiPoint)     return transformMultiPoint((MultiPoint) inputGeom, null);
    if (inputGeom instanceof LinearRing)     return transformLinearRing((LinearRing) inputGeom, null);
    if (inputGeom instanceof LineString)     return transformLineString((LineString) inputGeom, null);
    if (inputGeom instanceof MultiLineString)return transformMultiLineString(...);
    if (inputGeom instanceof Polygon)        return transformPolygon((Polygon) inputGeom, null);
    if (inputGeom instanceof MultiPolygon)   return transformMultiPolygon(...);
    if (inputGeom instanceof GeometryCollection) return transformGeometryCollection(...);
    throw new IllegalArgumentException("Unknown geometry type: " + inputGeom.getClass().getSimpleName());
  }

  protected Geometry transformPoint(Point geom, Geometry parent) { ... }
  protected Geometry transformLineString(LineString geom, Geometry parent) { ... }
  protected Geometry transformPolygon(Polygon geom, Geometry parent) { ... }
  // ...
}

package com.example.jtsext;

import org.locationtech.jts.geom.Coordinate;
import org.locationtech.jts.geom.CoordinateList;
import org.locationtech.jts.geom.Geometry;
import org.locationtech.jts.geom.LineString;
import org.locationtech.jts.geom.util.GeometryTransformer;

/**
 * 把几何中所有线串按其自身长度等分加密到指定间距。
 * 与 {@code Densifier} 的区别：这是按“顶点数”补齐，不是按距离插点。
 */
public class VertexDensifyTransformer extends GeometryTransformer {

  private final int minVertexCount;

  public VertexDensifyTransformer(int minVertexCount) {
    if (minVertexCount < 2) {
      throw new IllegalArgumentException("minVertexCount must be >= 2");
    }
    this.minVertexCount = minVertexCount;
  }

  @Override
  protected Geometry transformLineString(LineString geom, Geometry parent) {
    if (geom.getNumPoints() >= minVertexCount) {
      return super.transformLineString(geom, parent);
    }
    Coordinate[] pts = geom.getCoordinates();
    CoordinateList out = new CoordinateList();
    int segments = minVertexCount - 1;
    for (int i = 0; i < pts.length - 1; i++) {
      Coordinate a = pts[i];
      Coordinate b = pts[i + 1];
      for (int k = 0; k < segments; k++) {
        double t = (double) k / segments;
        out.add(new Coordinate(
            a.x + (b.x - a.x) * t,
            a.y + (b.y - a.y) * t), false);
      }
    }
    out.add(pts[pts.length - 1], false);
    return factory.createLineString(out.toCoordinateArray());
  }

  private VertexDensifyTransformer() {
    this(2);
  }
}

WKTReader reader = new WKTReader(new GeometryFactory());
Geometry in = reader.read("LINESTRING (0 0, 30 0)");

Geometry out = new VertexDensifyTransformer(4).transform(in);
System.out.println(out);

package com.example.jtsext;

import java.util.ArrayList;
import java.util.List;

import org.locationtech.jts.geom.Geometry;
import org.locationtech.jts.geom.util.GeometryMapper;

/**
 * 对几何中每个元素做变换，丢弃空结果，重新组装。
 */
public class MapFunctions {

  /**
   * 把每个元素向外扩 1 个单位并合并重叠部分。
   */
  public static Geometry expandAndMerge(Geometry geom) {
    return GeometryMapper.map(geom, new GeometryMapper.MapOp() {
      public Geometry map(Geometry g) {
        return g.buffer(1.0);
      }
    }).union();
  }

  /**
   * 只保留面积大于阈值的面。
   */
  public static Geometry filterByArea(Geometry geom, final double minArea) {
    List<Geometry> kept = new ArrayList<Geometry>();
    for (int i = 0; i < geom.getNumGeometries(); i++) {
      Geometry g = geom.getGeometryN(i);
      if (g.getArea() >= minArea) kept.add(g);
    }
    return geom.getFactory().buildGeometry(kept);
  }

  private MapFunctions() {
  }
}

package org.locationtech.jtslab;

import org.locationtech.jts.geom.Envelope;
import org.locationtech.jts.geom.Geometry;
import org.locationtech.jts.geom.PrecisionModel;
import org.locationtech.jtslab.clip.RectangleClipPolygon;

public class ClipFunctions {

  public static Geometry clipPoly(Geometry geom, Geometry rectangle) {
    return RectangleClipPolygon.clip(geom, rectangle);
  }

  public static Geometry clipPolyPrecise(Geometry geom, Geometry rectangle, double scaleFactor) {
    return RectangleClipPolygon.clip(geom, rectangle, new PrecisionModel(scaleFactor));
  }

  public static Geometry clipByIntersection(Geometry geom, Geometry rectangle) {
    Envelope rectEnv = rectangle.getEnvelopeInternal();
    if (rectEnv.contains(geom.getEnvelopeInternal())) return geom.copy();
    return rectangle.intersection(geom);
  }

  public static Geometry clipByIntersectionOpt(Geometry geom, Geometry rectangle) {
    Envelope rectEnv = rectangle.getEnvelopeInternal();
    if (rectEnv.contains(geom.getEnvelopeInternal())) return geom.copy();
    if (!rectangle.intersects(geom)) return null;
    return rectangle.intersection(geom);
  }
}

private static Geometry overlay(Geometry coll, boolean useNG, PrecisionModel pm) {
  List<Geometry> result = new ArrayList<Geometry>();
  for (int i = 0; i < coll.getNumGeometries(); i++) {
    Geometry inGeom = coll.getGeometryN(i);

    int size = result.size();
    for (int j = 0; j < size; j++) {
      Geometry resGeom = result.get(j);
      if (resGeom.isEmpty()) continue;

      Geometry intGeom = extractPolygons(overlayIntersection(resGeom, inGeom, useNG, pm));
      if (!intGeom.isEmpty()) {
        result.add(intGeom);

        Geometry resDiff = extractPolygons(overlayDifference(resGeom, intGeom, useNG, pm));
        result.set(j, resDiff);

        inGeom = extractPolygons(overlayDifference(inGeom, intGeom, useNG, pm));
      }
    }
    if (!inGeom.isEmpty()) {
      result.addAll(PolygonExtracter.getPolygons(inGeom));
    }
  }
  return coll.getFactory().buildGeometry(extractPolygonsNonEmpty(result));
}

package com.example.geo.spi;

import org.locationtech.jts.geom.Geometry;

/**
 * 面积计算策略。实现类通过 {@link java.util.ServiceLoader} 加载。
 */
public interface AreaCalculator {

  /**
   * 策略标识，全局唯一。
   *
   * @return 策略名，如 "planar"、"spherical"
   */
  String name();

  /**
   * 计算几何面积。
   *
   * @param geom 输入几何，非 null
   * @return 面积，单位由实现约定
   */
  double area(Geometry geom);
}

package com.example.geo.impl;

import org.locationtech.jts.geom.Geometry;

import com.example.geo.spi.AreaCalculator;

/**
 * 平面面积：直接使用 JTS 的笛卡尔面积。
 * <p>
 * 注意：当坐标系是经纬度（EPSG:4326）时，结果的单位是“平方度”，
 * 业务上通常没有意义，需要先投影或改用球面近似。
 */
public class PlanarAreaCalculator implements AreaCalculator {

  public String name() {
    return "planar";
  }

  public double area(Geometry geom) {
    if (geom == null || geom.isEmpty()) return 0.0;
    return geom.getArea();
  }
}

package com.example.geo;

import java.util.HashMap;
import java.util.Map;
import java.util.ServiceLoader;

import org.locationtech.jts.geom.Geometry;

import com.example.geo.spi.AreaCalculator;

/**
 * 面积服务：按名称选择策略，缺省用 planar。
 */
public class AreaService {

  private final Map<String, AreaCalculator> calculators = new HashMap<String, AreaCalculator>();

  public AreaService() {
    for (AreaCalculator c : ServiceLoader.load(AreaCalculator.class)) {
      calculators.put(c.name(), c);
    }
  }

  public double area(String strategy, Geometry geom) {
    AreaCalculator c = calculators.get(strategy);
    if (c == null) {
      throw new IllegalArgumentException("unknown strategy: " + strategy
          + ", available = " + calculators.keySet());
    }
    return c.area(geom);
  }

  public Map<String, AreaCalculator> available() {
    return calculators;
  }
}

package com.example.geo.process;

import org.geotools.api.feature.simple.SimpleFeature;
import org.geotools.process.factory.DescribeParameter;
import org.geotools.process.factory.DescribeProcess;
import org.geotools.process.factory.DescribeResult;
import org.geotools.process.factory.StaticMethodsProcessFactory;
import org.locationtech.jts.geom.Geometry;

/**
 * 把 JTS 算法包装成 GeoTools Process，从而可被 GeoServer 的 WPS 调用。
 */
@DescribeProcess(title = "Snap To Grid", description = "Snaps geometry coordinates to a grid")
public class SnapProcess {

  @DescribeResult(name = "result", description = "snapped geometry")
  public Geometry execute(
      @DescribeParameter(name = "geom", description = "input geometry") Geometry geom,
      @DescribeParameter(name = "gridSize", description = "grid size", min = 0) Double gridSize) {

    if (geom == null || geom.isEmpty() || gridSize == null || gridSize <= 0) {
      return geom;
    }
    // 直接复用 22.3 里写的 JTS 函数
    return com.example.jtsext.SnapFunctions.snapToGrid(geom, gridSize);
  }

  /**
   * 工厂：GeoTools 通过它发现 Process。
   */
  public static class Factory extends StaticMethodsProcessFactory<SnapProcess> {
    public Factory() {
      super(SnapProcess.class, "example", "Snap", SnapProcess.class);
    }
  }
}