Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,21 @@ ProjCoordinate result = new ProjCoordinate();
wgsToUtm.transform(new ProjCoordinate(lon, lat), result);
```

### CRS area of use

For an EPSG CRS, `getAreaOfUse()` returns its EPSG geographic area-of-use metadata, or
`null` when the CRS has no available metadata. Bounds and coordinates are in decimal
degrees (longitude, latitude); custom parameter-defined CRSs have no area-of-use metadata.
The metadata is distributed in the `proj4j-epsg` artifact.

```Java
AreaOfUse area = UTM.getAreaOfUse();
if (area != null) {
System.out.println(area.getWestLongitude() + ", " + area.getSouthLatitude()
+ " to " + area.getEastLongitude() + ", " + area.getNorthLatitude());
}
```

## Building, Testing and installing locally

`mvn clean install`
Expand Down
80 changes: 80 additions & 0 deletions core/src/main/java/org/locationtech/proj4j/AreaOfUse.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
/*
* Copyright 2026 PROJ4J contributors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.locationtech.proj4j;

import java.io.Serializable;

/**
* The geographic area in which a coordinate reference system is intended to be used.
*
* <p>Longitudes and latitudes are in decimal degrees, relative to Greenwich and the
* equator. Bounds may cross the antimeridian, in which case the west longitude is
* greater than the east longitude.</p>
*/
public final class AreaOfUse implements Serializable {

private static final long serialVersionUID = 1L;

private final String name;
private final double westLongitude;
private final double southLatitude;
private final double eastLongitude;
private final double northLatitude;

public AreaOfUse(String name, double westLongitude, double southLatitude,
double eastLongitude, double northLatitude) {
this.name = name;
this.westLongitude = westLongitude;
this.southLatitude = southLatitude;
this.eastLongitude = eastLongitude;
this.northLatitude = northLatitude;
}

/**
* Gets a description of the area of use.
*/
public String getName() {
return name;
}

/**
* Gets the westernmost longitude, in decimal degrees.
*/
public double getWestLongitude() {
return westLongitude;
}

/**
* Gets the southernmost latitude, in decimal degrees.
*/
public double getSouthLatitude() {
return southLatitude;
}

/**
* Gets the easternmost longitude, in decimal degrees.
*/
public double getEastLongitude() {
return eastLongitude;
}

/**
* Gets the northernmost latitude, in decimal degrees.
*/
public double getNorthLatitude() {
return northLatitude;
}
}
4 changes: 3 additions & 1 deletion core/src/main/java/org/locationtech/proj4j/CRSFactory.java
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,9 @@ public CoordinateReferenceSystem createFromName(String name)
String[] params = csReader.getParameters(name);
if (params == null)
throw new UnknownAuthorityCodeException(name);
return createFromParameters(name, params);
CoordinateReferenceSystem crs = createFromParameters(name, params);
crs.setAreaOfUse(csReader.getAreaOfUse(name));
return crs;
}

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ public class CoordinateReferenceSystem implements java.io.Serializable {
private String[] params;
private Datum datum;
private Projection proj;
private AreaOfUse areaOfUse;

public CoordinateReferenceSystem(String name, String[] params, Datum datum, Projection proj) {
this.name = name;
Expand Down Expand Up @@ -85,6 +86,20 @@ public Projection getProjection() {
return proj;
}

/**
* Gets the geographic area in which this CRS is intended to be used, or {@code null}
* if no area-of-use metadata is available.
*
* @return the area of use in decimal degrees, or {@code null}
*/
public AreaOfUse getAreaOfUse() {
return areaOfUse;
}

void setAreaOfUse(AreaOfUse areaOfUse) {
this.areaOfUse = areaOfUse;
}

public String getParameterString() {
if (params == null) return "";

Expand Down
63 changes: 63 additions & 0 deletions core/src/main/java/org/locationtech/proj4j/io/Proj4FileReader.java
Original file line number Diff line number Diff line change
Expand Up @@ -16,18 +16,26 @@
package org.locationtech.proj4j.io;

import org.locationtech.proj4j.util.Pair;
import org.locationtech.proj4j.AreaOfUse;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.StreamTokenizer;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Proj4FileReader {

private static final String AREA_OF_USE_RESOURCE = "proj4/area_of_use.tsv";

public Proj4FileReader() {
super();
}
Expand Down Expand Up @@ -124,6 +132,61 @@ public String[] getParameters(String crsName) {
return null;
}

/**
* Gets area-of-use metadata for an EPSG coordinate reference system.
*
* @param crsName the authority name of the coordinate reference system
* @return the area of use, or {@code null} if metadata is unavailable
*/
public AreaOfUse getAreaOfUse(String crsName) {
int separator = crsName.indexOf(':');
if (separator < 0 || !crsName.substring(0, separator).equalsIgnoreCase("EPSG")) {
return null;
}
return AreaOfUseData.AREAS.get(crsName.substring(separator + 1));
}

private static Map<String, AreaOfUse> readAreaOfUseData() {
InputStream input = Proj4FileReader.class.getClassLoader()
.getResourceAsStream(AREA_OF_USE_RESOURCE);
if (input == null) {
return Collections.emptyMap();
}

Map<String, AreaOfUse> areas = new HashMap<>();
try (BufferedReader reader = new BufferedReader(
new InputStreamReader(input, StandardCharsets.UTF_8))) {
String line;
while ((line = reader.readLine()) != null) {
if (line.isEmpty() || line.charAt(0) == '#') {
continue;
}
String[] fields = line.split("\t", 6);
if (fields.length != 6) {
throw new IllegalStateException("Invalid area-of-use entry: " + line);
}
AreaOfUse area = new AreaOfUse(
fields[5],
Double.parseDouble(fields[1]),
Double.parseDouble(fields[2]),
Double.parseDouble(fields[3]),
Double.parseDouble(fields[4]));
if (areas.put(fields[0], area) != null) {
throw new IllegalStateException("Duplicate area-of-use entry for EPSG:" + fields[0]);
}
}
} catch (IOException e) {
throw new UncheckedIOException("Unable to read area-of-use metadata", e);
} catch (NumberFormatException e) {
throw new IllegalStateException("Invalid numeric value in area-of-use metadata", e);
}
return Collections.unmodifiableMap(areas);
}

private static final class AreaOfUseData {
private static final Map<String, AreaOfUse> AREAS = readAreaOfUseData();
}

public String readEpsgCodeFromFile(String[] params) throws IOException {
InputStream inStr = Proj4FileReader.class.getClassLoader().getResourceAsStream("proj4/nad/epsg");

Expand Down
58 changes: 58 additions & 0 deletions core/src/test/java/org/locationtech/proj4j/AreaOfUseTest.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
/*
* Copyright 2026 PROJ4J contributors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.locationtech.proj4j;

import org.junit.Test;

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

public class AreaOfUseTest {

@Test
public void epsgAreaOfUseIsAvailable() {
CoordinateReferenceSystem crs = new CRSFactory().createFromName("EPSG:32633");
AreaOfUse area = crs.getAreaOfUse();

assertEquals(12, area.getWestLongitude(), 0);
assertEquals(0, area.getSouthLatitude(), 0);
assertEquals(18, area.getEastLongitude(), 0);
assertEquals(84, area.getNorthLatitude(), 0);
assertTrue(area.getName().contains("Between 12°E and 18°E"));
}

@Test
public void globalAndAntimeridianAreasRetainTheirBounds() {
CRSFactory factory = new CRSFactory();
AreaOfUse world = factory.createFromName("EPSG:4326").getAreaOfUse();
assertEquals(-180, world.getWestLongitude(), 0);
assertEquals(-90, world.getSouthLatitude(), 0);
assertEquals(180, world.getEastLongitude(), 0);
assertEquals(90, world.getNorthLatitude(), 0);

AreaOfUse americas = factory.createFromName("EPSG:8858").getAreaOfUse();
assertTrue(americas.getWestLongitude() > americas.getEastLongitude());
}

@Test
public void areaOfUseIsUnavailableForCustomCrs() {
CoordinateReferenceSystem crs = new CRSFactory().createFromParameters(
"custom", "+proj=longlat +datum=WGS84 +no_defs");

assertNull(crs.getAreaOfUse());
}
}
Loading
Loading