Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PM-Xpath implementation to calculate the distance from the boundary #1455

Open
wants to merge 7 commits into
base: master
Choose a base branch
from

Conversation

pm-dimagi
Copy link

@pm-dimagi pm-dimagi commented Jan 16, 2025

Product Description

Written down the functions that calculate the distance from the boundary of the polygon

Technical Summary

Followed this document for the implementation of the code logic(https://docs.google.com/document/d/1mEqXmtuLSBnPGzcvxyEg-3X7BBytAlEFb8epkbevO64/edit?usp=sharing)

Safety Assurance

Safety story

  • Not able to do developer testing

Automated test coverage

QA Plan

-Need proper testing to this function by creating the polygon and check the distance from that.

  • Xpath function for the same is XPathBoundaryDistanceFunc

Special deploy instructions

  • This PR can be deployed after merge with no further considerations.

Rollback instructions

  • This PR can be reverted after deploy with no further considerations.

Review

  • The set of people pinged as reviewers is appropriate for the level of risk of the change.

Duplicate PR

Automatically duplicate this PR as defined in contributing.md.

Summary by CodeRabbit

  • New Features

    • Added a new XPath function boundaryDistance() to calculate the distance to the closest polygon boundary
    • Introduced utility methods for geometric calculations involving polygons, including point-in-polygon checks and distance measurements
  • Technical Improvements

    • Enhanced XPath expression capabilities with spatial analysis functionality
    • Added support for geometric computations in the core library

Copy link

coderabbitai bot commented Jan 16, 2025

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

A new set of utility classes and methods have been added to the JavaRosa library to support advanced geospatial calculations. The changes introduce PolygonUtils for geometric computations, XPathBoundaryDistanceFunc as a new XPath function for calculating distances to polygon boundaries, and an update to FunctionUtils to register the new XPath function. These additions enable more sophisticated spatial analysis within XPath expressions, specifically for determining point-in-polygon and distance-to-boundary calculations.

Changes

File Change Summary
src/main/java/org/javarosa/core/model/utils/PolygonUtils.java New utility class with methods for geometric calculations:
- isPointInsidePolygon(): Checks if a point is inside a polygon
- distanceToClosestBoundary(): Calculates distance to polygon's nearest edge
src/main/java/org/javarosa/xpath/expr/FunctionUtils.java Added registration for new XPathBoundaryDistanceFunc in function list
src/main/java/org/javarosa/xpath/expr/XPathBoundaryDistanceFunc.java New XPath function class for calculating boundary distances with support for parsing geographic coordinates

Sequence Diagram

sequenceDiagram
    participant XPath as XPath Expression
    participant BoundaryFunc as XPathBoundaryDistanceFunc
    participant PolygonUtils as PolygonUtils
    
    XPath->>BoundaryFunc: Evaluate boundaryDistance()
    BoundaryFunc->>BoundaryFunc: Parse coordinates
    BoundaryFunc->>PolygonUtils: Calculate distance to boundary
    PolygonUtils-->>BoundaryFunc: Return distance
    BoundaryFunc-->>XPath: Return result
Loading

Poem

🐰 A Rabbit's Geospatial Delight

In lines of code, a polygon's might,
Boundaries measured, distances bright,
XPath now dances with spatial grace,
Calculating points with mathematical embrace,
A geometric journey, pure and light! 🗺️


Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

❤️ Share
🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Generate unit testing code for this file.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai generate unit testing code for this file.
    • @coderabbitai modularize this function.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and generate unit testing code.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
    • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai generate docstrings to generate docstrings for this PR. (Beta)
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

  • You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
  • Please see the configuration documentation for more information.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

@pm-dimagi pm-dimagi requested a review from shubham1g5 January 16, 2025 11:29
Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🧹 Nitpick comments (5)
src/main/java/org/javarosa/xpath/expr/XPathBoundaryDistanceFunc.java (2)

36-37: Throw an exception instead of returning -1.0 for invalid inputs

Returning -1.0 to indicate an error may lead to ambiguity in the calling code. Throwing an exception provides clearer error handling and prevents the propagation of invalid values.

Apply this diff to improve error handling:

- if (unpackedFrom == null || "".equals(unpackedFrom) || unpackedTo == null || "".equals(unpackedTo)) {
-     return Double.valueOf(-1.0);
- }
+ if (unpackedFrom == null || "".equals(unpackedFrom) || unpackedTo == null || "".equals(unpackedTo)) {
+     throw new XPathTypeMismatchException("boundaryDistance() function requires non-empty string arguments.");
+ }

52-53: Correct the function name in the exception message

The exception message incorrectly refers to "distance()" instead of "boundaryDistance()". Updating it helps avoid confusion.

Apply this diff to correct the message:

- throw new XPathTypeMismatchException("distance() function requires arguments containing " +
+ throw new XPathTypeMismatchException("boundaryDistance() function requires arguments containing " +
src/main/java/org/javarosa/core/model/utils/PolygonUtils.java (2)

14-33: Optimize isPointInsidePolygon method for performance

Consider optimizing the isPointInsidePolygon method by utilizing existing geometry libraries or algorithms optimized for computational efficiency, especially if this method will be called frequently or on large datasets.


73-91: Validate input data in distanceToClosestBoundary

Adding input validation can prevent potential errors due to malformed or empty inputs. Ensuring that polygonPoints contains an even number of elements and that testPoint has the correct length enhances robustness.

Apply this diff to add input validation:

 public static double distanceToClosestBoundary(List<Double> polygonPoints, double[] testPoint) {
+     if (polygonPoints == null || polygonPoints.size() < 6 || polygonPoints.size() % 2 != 0) {
+         throw new IllegalArgumentException("polygonPoints must contain pairs of latitude and longitude coordinates.");
+     }
+     if (testPoint == null || testPoint.length != 2) {
+         throw new IllegalArgumentException("testPoint must contain latitude and longitude.");
+     }
src/main/java/org/javarosa/xpath/expr/FunctionUtils.java (1)

93-93: Maintain alphabetical order in funcList for readability

The funcList is primarily organized alphabetically. Consider inserting XPathBoundaryDistanceFunc in the appropriate alphabetical position to improve maintainability.

Apply this diff to reorder the entry:

 funcList.put(XPathChecksumFunc.NAME, XPathChecksumFunc.class);
+funcList.put(XPathBoundaryDistanceFunc.NAME, XPathBoundaryDistanceFunc.class);
 funcList.put(XPathSortFunc.NAME, XPathSortFunc.class);

(Note: Adjust the insertion point based on the correct alphabetical order.)

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7d747e3 and ac492df.

📒 Files selected for processing (3)
  • src/main/java/org/javarosa/core/model/utils/PolygonUtils.java (1 hunks)
  • src/main/java/org/javarosa/xpath/expr/FunctionUtils.java (1 hunks)
  • src/main/java/org/javarosa/xpath/expr/XPathBoundaryDistanceFunc.java (1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (8)
  • GitHub Check: task-list-completed
  • GitHub Check: task-list-completed
  • GitHub Check: task-list-completed
  • GitHub Check: task-list-completed
  • GitHub Check: task-list-completed
  • GitHub Check: task-list-completed
  • GitHub Check: task-list-completed
  • GitHub Check: task-list-completed

Comment on lines 14 to 56
public class XPathBoundaryDistanceFunc extends XPathFuncExpr{
public static final String NAME = "boundaryDistance";
private static final int EXPECTED_ARG_COUNT = 2;

public XPathBoundaryDistanceFunc() {
name = NAME;
expectedArgCount = EXPECTED_ARG_COUNT;
}

public XPathBoundaryDistanceFunc(XPathExpression[] args) throws XPathSyntaxException {
super(NAME, args, EXPECTED_ARG_COUNT, true);
}


@Override
protected Object evalBody(DataInstance model, EvaluationContext evalContext, Object[] evaluatedArgs) {
return boundaryDistance(evaluatedArgs[0], evaluatedArgs[1]);
}

public static Double boundaryDistance(Object from, Object to) {
String unpackedFrom = (String)FunctionUtils.unpack(from);
String unpackedTo = (String)FunctionUtils.unpack(to);
if (unpackedFrom == null || "".equals(unpackedFrom) || unpackedTo == null || "".equals(unpackedTo)) {
return Double.valueOf(-1.0);
}
try {
String[] coordinates=unpackedFrom.split(" ");
List<Double> polygonList = new ArrayList<Double>();

for (String coordinate : coordinates) {
polygonList.add(Double.parseDouble(coordinate));
}
// Casting and uncasting seems strange but is consistent with the codebase
GeoPointData castedTo = new GeoPointData().cast(new UncastData(unpackedTo));
double distance=PolygonUtils.distanceToClosestBoundary(polygonList,new double[]{castedTo.getLatitude(), castedTo.getLongitude()});

return distance;
} catch (NumberFormatException e) {
throw new XPathTypeMismatchException("distance() function requires arguments containing " +
"numeric values only, but received arguments: " + unpackedFrom + " and " + unpackedTo);
}
}
}
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Add unit tests for XPathBoundaryDistanceFunc

To ensure the correctness and robustness of the boundaryDistance function, it's crucial to add unit tests covering various scenarios, including valid inputs, invalid inputs, and edge cases.

Would you like assistance in generating unit tests for this function or opening a GitHub issue to track this task?

Comment on lines 34 to 35
String unpackedFrom = (String)FunctionUtils.unpack(from);
String unpackedTo = (String)FunctionUtils.unpack(to);
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Ensure safe casting from FunctionUtils.unpack(from/to)

Casting the result of FunctionUtils.unpack() directly to String may lead to a ClassCastException if the unpacked objects are not strings. It's advisable to check the instance type before casting to prevent potential runtime exceptions.

Apply this diff to safely handle the casting:

- String unpackedFrom = (String)FunctionUtils.unpack(from);
- String unpackedTo = (String)FunctionUtils.unpack(to);
+ Object unpackedFromObj = FunctionUtils.unpack(from);
+ Object unpackedToObj = FunctionUtils.unpack(to);
+ if (!(unpackedFromObj instanceof String) || !(unpackedToObj instanceof String)) {
+     throw new XPathTypeMismatchException("boundaryDistance() function requires string arguments.");
+ }
+ String unpackedFrom = (String) unpackedFromObj;
+ String unpackedTo = (String) unpackedToObj;
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
String unpackedFrom = (String)FunctionUtils.unpack(from);
String unpackedTo = (String)FunctionUtils.unpack(to);
Object unpackedFromObj = FunctionUtils.unpack(from);
Object unpackedToObj = FunctionUtils.unpack(to);
if (!(unpackedFromObj instanceof String) || !(unpackedToObj instanceof String)) {
throw new XPathTypeMismatchException("boundaryDistance() function requires string arguments.");
}
String unpackedFrom = (String) unpackedFromObj;
String unpackedTo = (String) unpackedToObj;

Comment on lines 14 to 119

for (int i = 0; i < vertexCount; i++) {
double lat1 = polygonPoints.get(2 * i);
double lng1 = polygonPoints.get(2 * i + 1);
double lat2 = polygonPoints.get((2 * ((i + 1) % vertexCount)));
double lng2 = polygonPoints.get((2 * ((i + 1) % vertexCount)) + 1);

if (rayIntersectsEdge(testLat, testLng, lat1, lng1, lat2, lng2)) {
intersectCount++;
}
}

return (intersectCount % 2 == 1);
}

/**
* Checks if a ray starting from the test point intersects the edge defined by two vertices.
*/
private static boolean rayIntersectsEdge(double testLat, double testLng, double lat1, double lng1, double lat2, double lng2) {
if (lat1 > lat2) {
double tempLat = lat1, tempLng = lng1;
lat1 = lat2;
lng1 = lng2;
lat2 = tempLat;
lng2 = tempLng;
}

if (testLat < lat1 || testLat > lat2) {
return false;
}

if (testLng > Math.max(lng1, lng2)) {
return false;
}

if (testLng < Math.min(lng1, lng2)) {
return true;
}

double slope = (lng2 - lng1) / (lat2 - lat1);
double intersectLng = lng1 + (testLat - lat1) * slope;

return testLng < intersectLng;
}

/**
* Calculates the distance from a point to the closest boundary of the polygon.
*
* @param polygonPoints A list of doubles representing the polygon vertices
* (latitude and longitude pairs).
* @param testPoint A list of doubles representing the latitude and longitude of the test point.
* @return The distance from the test point to the closest edge of the polygon.
*/
public static double distanceToClosestBoundary(List<Double> polygonPoints, double[] testPoint) {
double minDistance = Double.MAX_VALUE;

int vertexCount = polygonPoints.size() / 2;
double testLat = testPoint[0];
double testLng = testPoint[1];

for (int i = 0; i < vertexCount; i++) {
double lat1 = polygonPoints.get(2 * i);
double lng1 = polygonPoints.get(2 * i + 1);
double lat2 = polygonPoints.get((2 * ((i + 1) % vertexCount)));
double lng2 = polygonPoints.get((2 * ((i + 1) % vertexCount)) + 1);

double distance = pointToSegmentDistance(testLat, testLng, lat1, lng1, lat2, lng2);
minDistance = Math.min(minDistance, distance);
}

return minDistance;
}

/**
* Calculates the shortest distance from a point to a line segment.
*/
private static double pointToSegmentDistance(double px, double py, double x1, double y1, double x2, double y2) {
double dx = x2 - x1;
double dy = y2 - y1;

if (dx == 0 && dy == 0) {
// The segment is a point
return Math.sqrt(Math.pow(px - x1, 2) + Math.pow(py - y1, 2));
}

// Calculate the projection of the point onto the line
double t = ((px - x1) * dx + (py - y1) * dy) / (dx * dx + dy * dy);

if (t < 0) {
// Closest to the first endpoint
return Math.sqrt(Math.pow(px - x1, 2) + Math.pow(py - y1, 2));
} else if (t > 1) {
// Closest to the second endpoint
return Math.sqrt(Math.pow(px - x2, 2) + Math.pow(py - y2, 2));
} else {
// Closest to a point on the segment
double projX = x1 + t * dx;
double projY = y1 + t * dy;
return Math.sqrt(Math.pow(px - projX, 2) + Math.pow(py - projY, 2));
}
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Add unit tests for PolygonUtils methods

Implementing unit tests for isPointInsidePolygon and distanceToClosestBoundary methods will help ensure their correctness and detect any regressions in future changes.

Would you like assistance in creating unit tests for these methods?

Copy link
Contributor

@shubham1g5 shubham1g5 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure I understand how this function is supposed to use. Do you mind writing some unit-tests to demonstrate the function usage in here

package org.javarosa.core.model.utils;
import java.util.List;

public class PolygonUtils {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

curious if this implementation was taken from somewhere , if so it might be good to reference it in a comment just in case we need to track any future updates to this code.

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

public class XPathBoundaryDistanceFunc extends XPathFuncExpr{
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we add a javadoc here explaining what this function does.

@pm-dimagi pm-dimagi requested a review from shubham1g5 January 16, 2025 21:34
@ctsims
Copy link
Member

ctsims commented Jan 17, 2025

@ctsims
Copy link
Member

ctsims commented Jan 23, 2025

Now that this is in a limited test, I wanted to make sure to write down a list of the things that I think need to be addressed in the structure before this is ready for production, since I might not be around or remember the context in full.

  • Implement appropriate sphere projection (great circle) math instead of planar math, and document the source of the approach
  • Address edge cases for inputs (like a malformed polygon) to make sure they are communicated as effectively as possible, and add tests to clarify how invalid inputs caught
  • Review the interfaces for the new functions (method signatures and names) - I don't think these are named super clearly right now, and I think the arguments should be in the other order (single input first, polygon second)
  • Make a decision about the best set of data formats / models to be used for portable Geospatial geometries
  • Prepare the documentation for these functions, as well as any supporting documentation to use them (both things like the data format for the portable geometries and helpful usage documentation next to the reference docs that explain the use cases and how someone would adopt them.
  • Provide references from initial testing to confirm that these methods are useful and complete enough from a Product perspective, and worth adding to the generally available platform.

@pm-dimagi
Copy link
Author

pm-dimagi commented Jan 27, 2025 via email

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants