Skip to content

Commit c3115a0

Browse files
S2 AuthorsTorreyHoffman
S2 Authors
authored and
TorreyHoffman
committed
Project import generated by Copybara.
PiperOrigin-RevId: 485144355
1 parent 5bd8781 commit c3115a0

201 files changed

Lines changed: 29026 additions & 7472 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,4 @@
22
build/
33
target/
44
.project
5-
.classpath
6-
.settings
5+
.classpath

‎README.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# S2 Geometry Library
2+
3+
## Overview
4+
5+
This is a package for manipulating geometric shapes. Unlike many geometry
6+
libraries, S2 is primarily designed to work with _spherical geometry_, i.e.,
7+
shapes drawn on a sphere rather than on a planar 2D map. This makes it
8+
especially suitable for working with geographic data.
9+
10+
If you want to learn more about the library, start by reading the
11+
[overview](http://s2geometry.io/about/overview) and [quick start
12+
document](http://s2geometry.io/devguide/cpp/quickstart), then read the
13+
introduction to the [basic types](http://s2geometry.io/devguide/basic_types).
14+
15+
S2 documentation can be found on [s2geometry.io](http://s2geometry.io).
16+
17+
## Build and Install
18+
19+
You may either download the source as a ZIP archive, or [clone the git
20+
repository](https://help.github.com/articles/cloning-a-repository/).
21+
The Java packages are built and tested using [Maven](https://maven.apache.org/).
22+
23+
In the directory containing the ```pom.xml``` file, use Maven to
24+
compile the package, run tests, and install the package. For example:
25+
26+
```
27+
mvn clean
28+
mvn compile
29+
mvn test
30+
mvn package
31+
mvn install
32+
```
33+
34+
### Benchmarks
35+
36+
After building packages, a "benchmarks.jar" file may be found in
37+
```benchmarks/target/```. Benchmarks can then be run with the command
38+
```java -jar benchmarks/target/benchmarks.jar```
39+
Parameters for the benchmarks can be passed on the command line. For example, to
40+
run just the S2Loop benchmarks,
41+
```java -jar benchmarks/target/benchmarks.jar S2Loop```
42+
43+
## S2 implementations
44+
45+
The S2 library has implementations in several languages. In addition to this
46+
Java implementation, Google provides:
47+
48+
* [C++](https://github.com/google/s2geometry) (The reference implementation
49+
and the most full featured).
50+
* [Go](https://github.com/golang/geo) (Approximately 40% complete.)
51+
* [Python](https://github.com/google/s2geometry/tree/master/src/python)
52+
53+
We (the S2 developers) aim to provide similar classes and APIs across all
54+
implementations, while adapting to language idioms where that makes sense, and
55+
changing APIs where required for good performance. The implementations have
56+
varying degrees of completeness and maturity. This Java implementation is
57+
heavily used within Google and is generally mature, aside from the newest
58+
features, but is not as complete as C++.
59+
60+
## 2022 Q4 Release Highlights
61+
62+
Many improvements have been made to the Java implementation of S2 since the last
63+
release in September 2021. Some highlights:
64+
65+
* Implementations of S2ClosestEdgeQuery and S2FurthestEdgeQuery, as well as
66+
S2ChainInterpolationQuery and S2HausdorffDistanceQuery.
67+
68+
* New tools for clustering and sharding data: S2RegionSharder and
69+
S2DensityTree.
70+
71+
* Support for map projections in MercatorProjection, PlateCarreeProjection,
72+
and S2EdgeTesselator.
73+
74+
* S2Coder implementations are now complete and should be interoperable
75+
between Go, C++ and Java.
76+
77+
* New Java implementation benchmarks based on JMH, the [Java Microbenchmark
78+
Harness](https://github.com/openjdk/jmh).
79+
80+
* Addition of S2IndexingHelper, which supports spatial indexing of regions
81+
in documents and finding document regions that intersect a query region.
82+
83+
* Many new methods on existing classes adding features which had formerly been
84+
missing in Java compared to the C++ implementation.
85+
86+
* Many Javadoc and other comment improvements.
87+
88+
* Many implementation cleanups. Most should not cause visible changes, but
89+
there were some bug fixes for improved accuracy.
90+
91+
* @CheckReturnValue is a package-wide default now, set in the newly added
92+
"package-info.java".
93+
94+
* The "testdatagenerator" subpackage supports generation of test data for both
95+
benchmarks and unit tests. Note that the APIs in this package are not
96+
part of the external S2 API and are subject to change without notice.
97+
98+
### Breaking API changes:
99+
100+
* We are now using Java 11, updating from Java 8, and beginning to use Java
101+
11 language features.
102+
103+
* Class Matrix3x3 was renamed Matrix.
104+
105+
* S2.simpleCrossing(a, b, c, d) has been removed as redundant; S2EdgeUtil
106+
provides the same API along with robustCrossing() and the EdgeCrosser class.
107+
108+
* A bug fix for EdgeCrosser.robustCrossing() may break clients that were
109+
relying on robustCrossing() to detect both repeated vertices in polylines
110+
and self-intersecting polylines. Specifically, for degenerate edges that
111+
don't have shared endpoints, robustCrossing now returns -1 to indicate "No
112+
Crossing" while previously it would return 0. Now, a return value of 0 is
113+
used only to indicate that two points from different edges are the same,
114+
i.e. edges touch. This now behaves exactly like the equivalent
115+
CrossingSign() in C++ for degenerate edges.
116+
117+
* Removed S2CellId.toTokenOld().
118+
119+
* The nested class RangeIterator was moved from S2ShapeIndex to S2ShapeUtil.
120+
121+
* The nested classes AreaMeasure, CentroidMeasure, and AreaCentroidMeasure
122+
were removed as they were redundant. Instead, use the methods in
123+
S2ShapeMeasures to compute centroids and areas for S2Shapes.
124+
125+
* Support for GWT has been removed. Support for J2CL is in progress but
126+
incomplete. The JS API is not final.
127+
128+
## Disclaimer
129+
130+
This is not an official Google product.

‎benchmarks/pom.xml‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
Copyright (C) 2022 Google, Inc.
4+
5+
Licensed under the Apache License, Version 2.0 (the "License");
6+
you may not use this file except in compliance with the License.
7+
You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
-->
17+
18+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
19+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
20+
<modelVersion>4.0.0</modelVersion>
21+
22+
<parent>
23+
<groupId>com.google.geometry</groupId>
24+
<artifactId>s2-geometry-parent</artifactId>
25+
<version>${revision}</version>
26+
</parent>
27+
28+
<name>S2 Geometry Library Benchmarks</name>
29+
30+
<artifactId>s2-geometry-benchmarks</artifactId>
31+
<packaging>jar</packaging>
32+
33+
<properties>
34+
<jmh.version>1.35</jmh.version>
35+
<uberjar.name>benchmarks</uberjar.name>
36+
<javac.target>1.8</javac.target>
37+
</properties>
38+
39+
<dependencies>
40+
<dependency>
41+
<groupId>com.google.geometry</groupId>
42+
<artifactId>s2-geometry-library</artifactId>
43+
<version>${project.parent.version}</version>
44+
</dependency>
45+
46+
<dependency>
47+
<groupId>com.google.geometry</groupId>
48+
<artifactId>s2-geometry-testdatagenerator</artifactId>
49+
<version>${project.parent.version}</version>
50+
</dependency>
51+
52+
<dependency>
53+
<groupId>org.openjdk.jmh</groupId>
54+
<artifactId>jmh-core</artifactId>
55+
<version>${jmh.version}</version>
56+
</dependency>
57+
58+
<dependency>
59+
<groupId>org.openjdk.jmh</groupId>
60+
<artifactId>jmh-generator-annprocess</artifactId>
61+
<version>${jmh.version}</version>
62+
<scope>provided</scope>
63+
</dependency>
64+
</dependencies>
65+
66+
<build>
67+
<sourceDirectory>src</sourceDirectory>
68+
<testSourceDirectory>tests</testSourceDirectory>
69+
70+
<plugins>
71+
72+
<plugin>
73+
<groupId>org.apache.maven.plugins</groupId>
74+
<artifactId>maven-compiler-plugin</artifactId>
75+
<version>3.8.0</version>
76+
<configuration>
77+
<compilerVersion>${javac.target}</compilerVersion>
78+
<source>${javac.target}</source>
79+
<target>${javac.target}</target>
80+
</configuration>
81+
</plugin>
82+
83+
<plugin>
84+
<groupId>org.apache.maven.plugins</groupId>
85+
<artifactId>maven-surefire-plugin</artifactId>
86+
<version>${surefire.version}</version>
87+
<configuration>
88+
<forkMode>always</forkMode>
89+
<redirectTestOutputToFile>true</redirectTestOutputToFile>
90+
</configuration>
91+
</plugin>
92+
93+
<plugin>
94+
<groupId>org.apache.maven.plugins</groupId>
95+
<artifactId>maven-shade-plugin</artifactId>
96+
<version>3.2.1</version>
97+
<executions>
98+
<execution>
99+
<phase>package</phase>
100+
<goals>
101+
<goal>shade</goal>
102+
</goals>
103+
<configuration>
104+
<finalName>${uberjar.name}</finalName>
105+
<transformers>
106+
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
107+
<mainClass>org.openjdk.jmh.Main</mainClass>
108+
</transformer>
109+
<transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
110+
</transformers>
111+
<filters>
112+
<filter>
113+
<!-- Shading signed JARs will fail without this. -->
114+
<artifact>*:*</artifact>
115+
<excludes>
116+
<exclude>META-INF/*.SF</exclude>
117+
<exclude>META-INF/*.DSA</exclude>
118+
<exclude>META-INF/*.RSA</exclude>
119+
</excludes>
120+
</filter>
121+
</filters>
122+
</configuration>
123+
</execution>
124+
</executions>
125+
</plugin>
126+
127+
</plugins>
128+
</build>
129+
130+
</project>

0 commit comments

Comments
 (0)