Extend docs to show edge cases of each method

[tordans]

I will quickly copy my testcase here in case someone else comes along and wonders about this.

My Question: How do the different methods handle cases where

• a line is within an area
  vs.
• a line is both in and out of an area

Conclusion: In my case, I want to use intersects which returns true for lines intersecting with the area.

contains:

de9im.contains(area, lineFullyWithinArea)) // ==> true
de9im.contains(area, lineInAndOutOfArea)) // ==> false

coveredby:

de9im.coveredby(lineFullyWithinArea, area)) // ==> true
de9im.coveredby(lineInAndOutOfArea, area)) // ==> false

crosses:

de9im.crosses(area, lineFullyWithinArea)) // ==> false
de9im.crosses(area, lineInAndOutOfArea)) // ==> true

intersects:

de9im.intersects(area, lineFullyWithinArea)) // ==> true
de9im.intersects(area, lineInAndOutOfArea)) // ==> true

within:

de9im.within(lineFullyWithinArea, area)) // ==> true
de9im.within(lineInAndOutOfArea, area)) // ==> false

The methods not listed here do not support this szenario.

Full test file

const area = {
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      properties: {},
      geometry: {
        type: "Polygon",
        coordinates: [
          [
            [13.587512969970701, 52.3013410761489],
            [13.619956970214844, 52.3013410761489],
            [13.619956970214844, 52.31141727938367],
            [13.587512969970701, 52.31141727938367],
            [13.587512969970701, 52.3013410761489],
          ],
        ],
      },
    },
  ],
}

const lineFullyWithinArea = {
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      properties: {},
      geometry: {
        type: "LineString",
        coordinates: [
          [13.594036102294922, 52.30595962063293],
          [13.613433837890625, 52.30784888634275],
        ],
      },
    },
  ],
}

const lineInAndOutOfArea = {
  type: "Feature",
  properties: {},
  geometry: {
    type: "LineString",
    coordinates: [
      [13.5955810546875, 52.30889844356715],
      [13.5955810546875, 52.313935971877584],
    ],
  },
}

import de9im from "de9im"

console.log(
  "de9im.contains(area, lineFullyWithinArea))",
  de9im.contains(area, lineFullyWithinArea)
)
console.log(
  "de9im.contains(area, lineInAndOutOfArea))",
  de9im.contains(area, lineInAndOutOfArea)
)
console.log(
  "de9im.coveredby(lineFullyWithinArea, area))",
  de9im.coveredby(lineFullyWithinArea, area)
)
console.log(
  "de9im.coveredby(lineInAndOutOfArea, area))",
  de9im.coveredby(lineInAndOutOfArea, area)
)
console.log(
  "de9im.crosses(area, lineFullyWithinArea))",
  de9im.crosses(area, lineFullyWithinArea)
)
console.log(
  "de9im.crosses(area, lineInAndOutOfArea))",
  de9im.crosses(area, lineInAndOutOfArea)
)
console.log(
  "de9im.intersects(area, lineFullyWithinArea))",
  de9im.intersects(area, lineFullyWithinArea)
)
console.log(
  "de9im.intersects(area, lineInAndOutOfArea))",
  de9im.intersects(area, lineInAndOutOfArea)
)
console.log(
  "de9im.within(lineFullyWithinArea, area))",
  de9im.within(lineFullyWithinArea, area)
)
console.log(
  "de9im.within(lineInAndOutOfArea, area))",
  de9im.within(lineInAndOutOfArea, area)
)

[dpmcmlxxvi]

The goal is to implement DE-9IM. So, hopefully, de9im should handle them however each predicate's intersection matrix dictates. But I understand that a user can get some nonintuitive results if the function names are used based on their informal English meaning and not their strict DE-9IM definitions. For example, a user might think:

• One of your lines and polygon above would overlap but not according to DE-9IM
• Two polygons should cross but never do not according to DE-9IM

Also, since there are so many combinations of predicates and geometries, I'll give some thought on which ones are obvious and which ones deserve being called out in the documentation.

[dpmcmlxxvi]

@tordans Closed with latest examples added to documentation.