Clarification/Rewording of CW and CCW polygons in geofencing_zones.json

[aswinthomas]

Hi,
I'm Aswin and I work at Google.

What is the issue and why is it an issue?

The wording used to specify whether one should use a CW(clockwise) or CCW(counter clockwise) polygon to specify an operational zone seems unclear or confusing.

The geoJSON spec says:
A linear ring MUST follow the right-hand rule with respect to the area it bounds, i.e., exterior rings are counterclockwise, and holes are clockwise.

Assuming I am only interested in the ride_allowed rule, based on the right hand rule, I should:

• create a CW polygon (a hole) with ride_allowed: false so that rides must start or end within this polygon.
• create a CCW polygon (a shell) with ride_allowed: false so that rides cannot start or end within this polygon.

However according to the GBFS spec:
A clockwise arrangement of points defines the area enclosed by the polygon, while a counterclockwise order defines the area outside the polygon.
An operational area (outside of which vehicles cannot be used) SHOULD be defined with a counterclockwise polygon, and a limitation area (in which vehicles can be used under certain restrictions) SHOULD be defined with a clockwise polygon.

What does area outside the polygon mean exactly?

Please describe some potential solutions you have considered (even if they aren’t related to GBFS).

We could update the directions, for example:
A counterclockwise arrangement of points defines the rules for the area enclosed by the polygon, while a clockwise order defines the rules for the area outside the polygon.

Since the direction of the polygon alone does not define whether it is operational or not, maybe specify ride_allowed as well. For example:

An operational area (outside of which vehicles cannot be used) SHOULD be defined with a clockwise polygon and the restriction e.g. ride_allowed: false, and a limitation area (in which vehicles can be used under certain restrictions) SHOULD be defined with a counterclockwise polygon and the restriction e.g. ride_allowed: false.

Is your potential solution a breaking change?

• Yes
• No
• Unsure

[ncancelliere]

I am not sure if this makes it any more understandable. I worry that it might confuse individuals even more. Drawing a polygon (going CCW) you end up defining the exterior shape (or service area). Then you are drawing additional CW polygons (holes) into that shape ... the result is like swiss cheese.

There isn't anything in the GeoJSON RFC, that I'm aware of, that says how rules need to be applied to said shapes (eg. inside or outside). So all the GBFS spec is saying is for CCW shapes the rules are defining what is outside the polygon, and for the CW shapes (holes) you're defining what happens inside that space. Because GBFS assumes no restrictions by default the inside of the CCW polygon has none, but the holes do.

At least this is how I interpret the GBFS spec. So I don't know that the spec needs to be so drastically altered. It might be better if their were examples included to explain the text better?

The change you are proposing would be backwards breaking since it's the opposite of what is in the spec today - assuming I'm interpreting it correctly.

[josee-sabourin]

Hi @aswinthomas, welcome to the repository!

@ncancelliere's explanation is the correct interpretation of the rules in the specification. We are planning to improve the documentation for geofencing_zones.json, better examples with visual explanations like the ones above will also be added. Hope that helps!

[balazsczap]

Hi everyone, I'm Balázs from TIER Mobility, working with @aswinthomas on our common integration.

While it's true that the GeoJSON spec doesn't specify how properties apply to Polygons, all our internal handling of Polygons are CCW with the rules applying to the surface bounded by the exterior ring. As far as I understand GBFS, it doesn't disallow this behaviour - "SHOULD be modeled according to restrictions" - but I understand that if we model according to restrictions, we must apply rules to the outside area of the Polygon to disallow riding outside of the service area.

With that in mind, what should happen if we have two fully separated service areas next to each other, with CCW polygons and ride_allowed: false? In our thinking, the insides of both polygons are implicitly ride_allowed: true but the explicit ride_allowed: false coming from the other polygon's external area make this scenario impossible.

As a sidenote, for station_information's station_area the interpretation is not specified at all, and based on the same assumptions we also use a CCW polygon there.

[mplsmitch]

@balazsczap

With that in mind, what should happen if we have two fully separated service areas next to each other, with CCW polygons and ride_allowed: false? In our thinking, the insides of both polygons are implicitly ride_allowed: true but the explicit ride_allowed: false coming from the other polygon's external area make this scenario impossible.

You could wrap your two separate service areas into a single area using CCW polygon with ride_allowed: false which would apply to the area outside the CCW polygon. Then create CW polygon with the same rule in the area between the two formerly separate service areas.

As a sidenote, for station_information's station_area the interpretation is not specified at all, and based on the same assumptions we also use a CCW polygon there.

I agree the documentation needs to be improved here but based on the geometry definition (below) from geofencing_zones.json I would think this would be CW since you are defining the space inside the polygon.

A clockwise arrangement of points defines the area enclosed by the polygon, while a counterclockwise order defines the area outside the polygon (right-hand rule).

[balazsczap]

Thanks @mplsmitch for the illustration, makes it clear. Another solution we've considered is to add the two business areas to a MultiPolygon, and rewinding them both to be CCW with ride_allowed: false, and as far as I understand the spec, the behaviour would be identical to the solution you described.

For the second part, I agree, the spec should apply the same rules to all GeoJSON objects in every feed.

[josee-sabourin]

Hi all! We talked about this issue during the Developers' Workshop, see details here - we wanted to let you know that we are working on the issue and there will be more updates soon.

[heidiguenin]

Mitch has put together a presentation detailing some of the current challenges with geofencing_zones.json and some proposed solutions - please check it out in Issue #404 !