The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
"""Approximate places (ONTOLOGY §2): a radius, a footprint, and how they got there.
The rules under test come from Darwin Core, which settled this for biodiversity
records two decades ago: the radius is the smallest circle containing the whole
location, **zero is not a valid radius** because empty already means unknown, and
the source's own wording outlives every reinterpretation of it.
The other half is that none of it is required. A place saved the way Satellite has
always saved one stays valid and complete, and an absent radius is a state rather
than a gap to fill.
"""
import pytest
from azimut.engine import entities
from azimut.workspace import Case, CaseError
def _new_case(client, name):
return client.post("/api/cases", json={"name": name}).json()["id"]
def _place(client, cid, **attrs):
res = client.post(
f"/api/cases/{cid}/entities",
json={"type": "place", "label": "Quay 4", "attrs": {"lat": 53.44, "lon": 14.55, **attrs}},
)
return res
def _patch(client, cid, eid, attrs):
return client.patch(f"/api/cases/{cid}/entities/{eid}", json={"attrs": attrs})
#: A ring around the point `_place` saves, which is where a place's own shape has to
#: be: lon first, closed, and the pin inside it rather than on a corner.
AROUND = [[14.54, 53.43], [14.56, 53.43], [14.56, 53.45], [14.54, 53.45], [14.54, 53.43]]
# -- nothing is required ------------------------------------------------------
def test_a_place_without_precision_is_still_valid(client):
"""The rule the whole feature answers to: today's saved place is unchanged."""
cid = _new_case(client, "Plain place")
res = _place(client, cid)
assert res.status_code == 200, res.text
assert "radius_m" not in res.json()["attrs"]
def test_clearing_a_field_is_how_unknown_is_written(client):
"""Refusing an empty value would make "I do not know how precise this is"
impossible to say, which is the state most places are actually in."""
cid = _new_case(client, "Cleared radius")
eid = _place(client, cid, radius_m=100).json()["id"]
assert _patch(client, cid, eid, {"radius_m": None}).status_code == 200
assert _patch(client, cid, eid, {"verbatim": ""}).status_code == 200
# -- the radius ---------------------------------------------------------------
def test_a_radius_records_the_smallest_enclosing_circle(client):
cid = _new_case(client, "Approximate place")
res = _place(
client, cid,
radius_m=500,
verbatim="près du vieux port, côté nord",
method="roofline matched against Esri imagery 2023-06",
)
assert res.status_code == 200, res.text
attrs = res.json()["attrs"]
assert attrs["radius_m"] == 500
# the source's own wording, unaltered: the field people wish they had kept
assert attrs["verbatim"] == "près du vieux port, côté nord"
assert attrs["method"].startswith("roofline matched")
# and the tool's own keys are untouched by any of it
assert attrs["lat"] == 53.44
def test_zero_is_not_a_valid_radius(client):
"""Darwin Core's rule, and the reason for it: empty means *unknown*, where `0`
would claim infinite precision. They are different states and both are needed."""
cid = _new_case(client, "Zero radius")
assert _place(client, cid, radius_m=0).status_code == 400
assert _place(client, cid, radius_m=-50).status_code == 400
def test_a_radius_must_be_a_finite_number(client):
cid = _new_case(client, "Odd radius")
assert _place(client, cid, radius_m="500").status_code == 400
# True is an int in Python, and `True` metres is not a radius
assert _place(client, cid, radius_m=True).status_code == 400
assert _place(client, cid, radius_m=entities.MAX_RADIUS_M + 1).status_code == 400
def test_an_infinite_radius_cannot_sneak_in_as_a_json_literal(client):
"""`json.dumps` refuses `inf`, so no ordinary client can send one — but
`json.loads` *accepts* the non-standard `Infinity` literal, which is how it would
actually arrive. Hence the finiteness check, tested through the real path."""
cid = _new_case(client, "Infinite radius")
res = client.post(
f"/api/cases/{cid}/entities",
content='{"type":"place","label":"Quay 4","attrs":{"radius_m":Infinity}}',
headers={"content-type": "application/json"},
)
assert res.status_code == 400, res.text
def test_the_rungs_are_served_with_the_field(client):
"""Metres are the right thing to store and the wrong thing to ask for, so the
ladder ships with the registry — one source for the picker and the validator."""
rows = {row["type"]: row for row in client.get("/api/cases/entity-types").json()}
radius = next(a for a in rows["place"]["attrs"] if a["key"] == "radius_m")
assert [rung["value"] for rung in radius["rungs"]] == [25, 100, 500, 2000, 10000]
assert radius["minimum"] == 1
assert radius["maximum"] == entities.MAX_RADIUS_M
# every rung is a value the API would accept
for rung in radius["rungs"]:
assert radius["minimum"] <= rung["value"] <= radius["maximum"]
def test_the_ladder_is_not_derived_from_plus_code_lengths():
"""Why the rungs are the input rather than the output: valid Plus Code lengths
jump from 8 (~280 m cells) straight to 6 (~5.6 km), and 300 m to 5 km is exactly
the band a live geolocation lives in. Two rungs sit inside that hole."""
values = [value for _, value in entities.PRECISION_RUNGS]
assert sorted(values) == values, "coarsest reading last"
assert [v for v in values if 280 < v < 5600] == [500, 2000]
# -- the footprint ------------------------------------------------------------
def test_a_footprint_holds_a_polygon_when_a_circle_is_the_wrong_shape(client):
cid = _new_case(client, "Footprint place")
res = _place(client, cid, footprint={"type": "Polygon", "coordinates": [AROUND]})
assert res.status_code == 200, res.text
assert res.json()["attrs"]["footprint"]["type"] == "Polygon"
def test_a_footprint_must_be_an_area(client):
"""A point is what lat/lon plus a radius already says, so a footprint that is
not an area carries no information the place did not have."""
cid = _new_case(client, "Not an area")
assert _place(
client, cid, footprint={"type": "Point", "coordinates": [14.55, 53.44]}
).status_code == 400
assert _place(
client, cid,
footprint={"type": "LineString", "coordinates": [[14.55, 53.44], [14.56, 53.45]]},
).status_code == 400
assert _place(
client, cid, footprint={"type": "Polygon", "coordinates": [[[14.55, 53.44]]]}
).status_code == 400
def test_a_footprint_is_refused_off_the_globe_or_malformed(client):
cid = _new_case(client, "Bad footprint")
def post(footprint):
return _place(client, cid, footprint=footprint).status_code
assert post("POLYGON((0 0))") == 400
assert post({"type": "Polygon"}) == 400
assert post({"type": "Polygon", "coordinates": []}) == 400
# lon then lat, and both on the globe
assert post({"type": "Polygon", "coordinates": [[[200, 0], [1, 1], [2, 2], [200, 0]]]}) == 400
assert post({"type": "Polygon", "coordinates": [[[0, 91], [1, 1], [2, 2], [0, 91]]]}) == 400
assert post({"type": "Polygon", "coordinates": [[[0], [1, 1], [2, 2], [0]]]}) == 400
assert post({"type": "Polygon", "coordinates": [[0, 0], [1, 0], [0, 1], [0, 0]]}) == 400
assert post({"type": "Polygon", "coordinates": [[[0, 0], [1, 0], [0, 1], [1, 1]]]}) == 400
assert post({"type": "MultiPolygon", "coordinates": [[]]}) == 400
def test_a_footprint_is_bounded_in_size_and_depth(client):
"""Validate at the edge: past a few thousand vertices this is a payload rather
than a shape, and nesting must not be a way around the count."""
cid = _new_case(client, "Huge footprint")
huge = [[0.001 * i, 0.001 * i] for i in range(entities.MAX_FOOTPRINT_POINTS + 2)]
assert _place(client, cid, footprint={"type": "Polygon", "coordinates": [huge]}).status_code == 400
deep = {"type": "Polygon", "coordinates": [[[[[[[0, 0]]]]]]]}
assert _place(client, cid, footprint=deep).status_code == 400
def test_a_footprint_must_contain_the_point_it_belongs_to(client):
"""A shape traced beside its pin describes somewhere else. The map let it happen:
the polygon drew where it was clicked and the pin stayed where it was, and nothing
said the two disagreed."""
cid = _new_case(client, "Shape elsewhere")
elsewhere = [[14.60, 53.50], [14.62, 53.50], [14.62, 53.52], [14.60, 53.50]]
res = _place(client, cid, footprint={"type": "Polygon", "coordinates": [elsewhere]})
assert res.status_code == 400
assert "contain" in res.json()["detail"]
def test_a_multipolygon_counts_as_containing_the_point_in_any_of_its_parts(client):
"""Two quays are one location, and the pin sits on one of them."""
cid = _new_case(client, "Two parts")
far = [[14.60, 53.50], [14.62, 53.50], [14.62, 53.52], [14.60, 53.50]]
res = _place(
client, cid, footprint={"type": "MultiPolygon", "coordinates": [[far], [AROUND]]}
)
assert res.status_code == 200, res.text
def test_a_point_inside_a_footprint_hole_is_refused(client):
cid = _new_case(client, "Point in a hole")
hole = [
[14.545, 53.435], [14.555, 53.435], [14.555, 53.445],
[14.545, 53.445], [14.545, 53.435],
]
res = _place(
client,
cid,
footprint={"type": "Polygon", "coordinates": [AROUND, hole]},
)
assert res.status_code == 400
assert "contain" in res.json()["detail"]
def test_a_polygon_boundary_covers_its_place(client):
cid = _new_case(client, "Point on boundary")
res = _place(
client,
cid,
lat=53.43,
footprint={"type": "Polygon", "coordinates": [AROUND]},
)
assert res.status_code == 200, res.text
def test_moving_a_place_must_stay_inside_its_retained_footprint(client):
cid = _new_case(client, "Moved point")
eid = _place(client, cid, footprint={"type": "Polygon", "coordinates": [AROUND]}).json()["id"]
assert _patch(client, cid, eid, {"lat": 54.0}).status_code == 400
assert _patch(client, cid, eid, {"lon": 15.0}).status_code == 400
assert _patch(client, cid, eid, {"lat": 54.0, "lon": 15.0}).status_code == 400
# Clearing the old shape in the same patch makes the move explicit.
assert _patch(client, cid, eid, {"lat": 54.0, "lon": 15.0, "footprint": None}).status_code == 200
def test_a_place_with_no_point_of_its_own_still_takes_a_footprint(client):
"""Nothing to contradict: a record promoted from a sheet can hold the shape
without holding the pair, and refusing it would lose the only geometry it has."""
cid = _new_case(client, "Shape only")
res = client.post(
f"/api/cases/{cid}/entities",
json={
"type": "place",
"label": "Quay 4",
"attrs": {"footprint": {"type": "Polygon", "coordinates": [AROUND]}},
},
)
assert res.status_code == 200, res.text
def test_a_place_states_its_precision_once(client):
"""A radius and a footprint answer the same question in two forms, and the map
draws one of them — so a radius typed over a traced shape used to vanish from the
map without a word. Writing one asks for the other to be cleared with it."""
cid = _new_case(client, "Both forms")
eid = _place(client, cid, radius_m=500).json()["id"]
shape = {"type": "Polygon", "coordinates": [AROUND]}
assert _patch(client, cid, eid, {"footprint": shape}).status_code == 400
assert _patch(client, cid, eid, {"footprint": shape, "radius_m": None}).status_code == 200
# and the same the other way round, which is the half an analyst types by hand
assert _patch(client, cid, eid, {"radius_m": 500}).status_code == 400
assert _patch(client, cid, eid, {"radius_m": 500, "footprint": None}).status_code == 200
def test_a_place_that_already_held_both_stays_editable(client):
"""The rule is judged on the patch, not on the stored result: a point written
before it holds both, and its notes must not become unsavable because of that."""
cid = _new_case(client, "Written earlier")
eid = _place(client, cid, radius_m=500).json()["id"]
case = Case.open(cid)
case.update_entity(eid, {"attrs": {"footprint": {"type": "Polygon", "coordinates": [AROUND]}}})
assert _patch(client, cid, eid, {"method": "caption only"}).status_code == 200
# …and touching either form is still what resolves it
assert _patch(client, cid, eid, {"radius_m": 100}).status_code == 400
# -- what validation does and does not reach ----------------------------------
def test_a_tools_own_keys_are_never_judged():
"""Only declared fields are checked. `notes`, `geo`, `plus_code` and the rest
belong to the save that made the point, so this stays additive: no write that
worked yesterday can start failing."""
entities.check_attrs("place", {"notes": 42, "geo": {"state": "ok"}, "zoom": "seventeen"})
def test_an_undeclared_type_is_not_judged_either():
entities.check_attrs("cuneiform-tablet", {"radius_m": 0})
def test_a_declared_url_must_be_http(client):
"""A declared url is rendered as a link, so the scheme is checked at the edge
rather than trusted."""
cid = _new_case(client, "Account url")
def account(url):
return client.post(
f"/api/cases/{cid}/entities",
json={"type": "account", "label": "@x", "attrs": {"url": url}},
).status_code
assert account("https://example.org/x") == 200
assert account("javascript:alert(1)") == 400
assert account("ftp://example.org/x") == 400
def test_the_engine_raises_rather_than_returning_a_verdict():
with pytest.raises(CaseError, match="at least 1"):
entities.check_attrs("place", {"radius_m": 0})
def test_every_editor_kind_is_used_by_some_field():
"""A kind nothing declares is an editor no screen can reach. `date` is absent on
purpose until the claim node's EDTF needs it."""
used = {attr.kind for entry in entities.ENTITY_TYPES for attr in entry.attrs}
assert used == set(entities.ATTR_KINDS)
# -- the update path ----------------------------------------------------------
def test_precision_can_be_added_to_a_place_that_already_exists(client):
"""The real workflow: a point is saved precisely, then the analyst admits it is
a guess. A partial patch must not disturb the geometry the tool wrote."""
cid = _new_case(client, "Later admission")
eid = _place(client, cid).json()["id"]
res = _patch(client, cid, eid, {"radius_m": 2000, "method": "caption only"})
assert res.status_code == 200, res.text
attrs = Case.open(cid).get_entity(eid)["attrs"]
assert attrs["radius_m"] == 2000
assert attrs["lat"] == 53.44 and attrs["lon"] == 14.55
def test_a_bad_patch_is_a_bad_request_not_a_missing_entity(client):
cid = _new_case(client, "Bad patch")
eid = _place(client, cid).json()["id"]
assert _patch(client, cid, eid, {"radius_m": 0}).status_code == 400
assert _patch(client, cid, "e_ghost", {"radius_m": 100}).status_code == 404
# -- reaching the map ---------------------------------------------------------
def test_the_saved_index_carries_the_precision_to_the_map(client):
"""The point of storing it: the overlay draws the circle, and it reads the saved
index rather than fetching each place. So precision that never reaches this row
is precision no analyst ever sees."""
cid = _new_case(client, "Index precision")
eid = _place(client, cid).json()["id"]
_patch(client, cid, eid, {"radius_m": 2000})
row = next(
r for r in client.get(f"/api/cases/{cid}/satellite/index").json() if r["id"] == eid
)
assert row["radius_m"] == 2000
assert row["footprint"] is None
def test_a_footprint_reaches_the_index_whole(client):
"""A traced shape says more than the circle around it, so the overlay gets the
geometry itself and not a bounding radius computed here."""
cid = _new_case(client, "Index footprint")
eid = _place(client, cid, footprint={"type": "Polygon", "coordinates": [AROUND]}).json()["id"]
row = next(
r for r in client.get(f"/api/cases/{cid}/satellite/index").json() if r["id"] == eid
)
assert row["footprint"] == {"type": "Polygon", "coordinates": [AROUND]}
def test_a_place_with_no_precision_states_none_in_the_index(client):
"""Absent is a state and travels as one: the overlay draws a plain pin for it,
which is how every place saved before this feature must keep rendering."""
cid = _new_case(client, "Index plain")
eid = _place(client, cid).json()["id"]
row = next(
r for r in client.get(f"/api/cases/{cid}/satellite/index").json() if r["id"] == eid
)
assert row["radius_m"] is None and row["footprint"] is None