heislime 1.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
heislime/__init__.py ADDED
@@ -0,0 +1,9 @@
1
+ from pathlib import Path
2
+
3
+ from semver import Version
4
+
5
+ project_root_dir = Path(__file__).parent.parent
6
+ project_cache_dir: Path = project_root_dir / 'cache'
7
+
8
+ __author__ = 'HeiGIT'
9
+ __version__: Version = Version.parse('1.1.1')
File without changes
@@ -0,0 +1,46 @@
1
+ from abc import ABC
2
+ from abc import abstractmethod
3
+
4
+ import geopandas as gpd
5
+ import pandas as pd
6
+ from pydantic import BaseModel
7
+ from pydantic import ConfigDict
8
+ from pydantic import Field
9
+
10
+ from heislime.osm.base import OSMProvider
11
+
12
+
13
+ class Enricher(BaseModel, ABC):
14
+ model_config = ConfigDict(frozen=True, extra='forbid')
15
+
16
+ column: str = Field(
17
+ min_length=1,
18
+ description='Name of the metadata entry added to every image',
19
+ )
20
+
21
+ @abstractmethod
22
+ def compute(self, sli_gdf: gpd.GeoDataFrame, osm_provider: OSMProvider) -> pd.DataFrame: ...
23
+
24
+ def enrich(self, sli_gdf: gpd.GeoDataFrame, osm_provider: OSMProvider) -> gpd.GeoDataFrame:
25
+ entries = self.compute(sli_gdf, osm_provider)
26
+
27
+ if len(entries) != len(sli_gdf):
28
+ raise RuntimeError(f'{type(self).__name__} returned {len(entries)} entries for {len(sli_gdf)} images')
29
+
30
+ if self.column not in entries.columns:
31
+ raise RuntimeError(f'{type(self).__name__} did not return its {self.column!r} entry')
32
+
33
+ entries = entries.set_axis(sli_gdf.index)
34
+
35
+ return sli_gdf.assign(**{str(name): entries[name] for name in entries.columns})
36
+
37
+
38
+ def enrich(
39
+ sli_gdf: gpd.GeoDataFrame,
40
+ enrichers: list[Enricher],
41
+ osm_provider: OSMProvider,
42
+ ) -> gpd.GeoDataFrame:
43
+ for enricher in enrichers:
44
+ sli_gdf = enricher.enrich(sli_gdf, osm_provider)
45
+
46
+ return sli_gdf
@@ -0,0 +1,260 @@
1
+ from abc import ABC
2
+ from abc import abstractmethod
3
+ from datetime import UTC
4
+ from datetime import datetime
5
+ from typing import Annotated
6
+ from typing import Literal
7
+
8
+ import geopandas as gpd
9
+ import numpy as np
10
+ import pandas as pd
11
+ from pydantic import BaseModel
12
+ from pydantic import ConfigDict
13
+ from pydantic import Field
14
+ from pydantic import field_validator
15
+ from pydantic import model_validator
16
+ from shapely.geometry import box
17
+
18
+ from heislime.enrich.base import Enricher
19
+ from heislime.osm.base import OSMProvider
20
+
21
+ SECONDS_PER_YEAR = 365.25 * 24 * 3600
22
+
23
+ SEASONS = ('winter', 'spring', 'summer', 'autumn')
24
+
25
+ Season = Literal['winter', 'spring', 'summer', 'autumn']
26
+
27
+
28
+ class Criterion(BaseModel, ABC):
29
+ model_config = ConfigDict(frozen=True, extra='forbid')
30
+
31
+ kind: str
32
+
33
+ weight: float = Field(
34
+ default=1.0,
35
+ gt=0,
36
+ description='Importance of the criterion relative to the other criteria',
37
+ )
38
+
39
+ name: str | None = Field(
40
+ default=None,
41
+ min_length=1,
42
+ description='Label of the criterion, defaults to its kind',
43
+ )
44
+
45
+ @property
46
+ def label(self) -> str:
47
+ return self.name or self.kind
48
+
49
+ @abstractmethod
50
+ def similarity(self, sli_gdf: gpd.GeoDataFrame, osm_provider: OSMProvider) -> np.ndarray: ...
51
+
52
+ @staticmethod
53
+ def _require(sli_gdf: gpd.GeoDataFrame, *columns: str):
54
+ if missing := [column for column in columns if column not in sli_gdf.columns]:
55
+ raise ValueError(f'sli_gdf must have {missing} columns')
56
+
57
+
58
+ class ProviderCriterion(Criterion):
59
+ kind: Literal['provider'] = 'provider'
60
+
61
+ scores: dict[str, Annotated[float, Field(ge=0, le=1)]] = Field(
62
+ min_length=1,
63
+ description='Similarity in [0, 1] of the images of every provider to the refence image',
64
+ )
65
+
66
+ default: float = Field(
67
+ default=0.0,
68
+ ge=0,
69
+ le=1,
70
+ description='Similarity of the images of providers missing from `scores`',
71
+ )
72
+
73
+ def similarity(self, sli_gdf: gpd.GeoDataFrame, osm_provider: OSMProvider) -> np.ndarray:
74
+ self._require(sli_gdf, 'provider')
75
+
76
+ return np.array(
77
+ [
78
+ np.nan if pd.isna(provider) else self.scores.get(str(provider), self.default)
79
+ for provider in sli_gdf['provider']
80
+ ],
81
+ dtype='float64',
82
+ )
83
+
84
+
85
+ class SeasonCriterion(Criterion):
86
+ kind: Literal['season'] = 'season'
87
+
88
+ seasons: list[Season] = Field(
89
+ min_length=1,
90
+ description='Preferred meteorological seasons',
91
+ )
92
+
93
+ hemisphere: Literal['auto', 'north', 'south'] = Field(
94
+ default='auto',
95
+ description='Hemisphere the seasons refer to; auto derives it from the latitude of every image',
96
+ )
97
+
98
+ def similarity(self, sli_gdf: gpd.GeoDataFrame, osm_provider: OSMProvider) -> np.ndarray:
99
+ self._require(sli_gdf, 'captured_at')
100
+
101
+ captured = pd.to_datetime(sli_gdf['captured_at'], utc=True)
102
+ month = captured.dt.month.to_numpy(dtype='float64', na_value=np.nan)
103
+
104
+ season = (month // 3) % 4
105
+ season = np.where(self._southern_hemisphere(sli_gdf), (season + 2) % 4, season)
106
+
107
+ preferred = np.array([SEASONS.index(s) for s in self.seasons], dtype='float64')
108
+ gap = np.abs(season[:, None] - preferred[None, :])
109
+ gap = np.minimum(gap, 4 - gap).min(axis=1)
110
+
111
+ return 1 - gap / 2
112
+
113
+ def _southern_hemisphere(self, sli_gdf: gpd.GeoDataFrame) -> np.ndarray:
114
+ if self.hemisphere != 'auto':
115
+ return np.full(len(sli_gdf), self.hemisphere == 'south')
116
+
117
+ if sli_gdf.crs is None:
118
+ raise ValueError('sli_gdf must have a CRS assigned')
119
+
120
+ return sli_gdf.geometry.to_crs('EPSG:4326').representative_point().y.to_numpy() < 0
121
+
122
+
123
+ class AgeCriterion(Criterion):
124
+ kind: Literal['age'] = 'age'
125
+
126
+ max_age: float = Field(
127
+ default=5.0,
128
+ gt=0,
129
+ description='Age (years) from which an image is as dissimilar to the reference image',
130
+ )
131
+
132
+ reference_time: datetime = Field(
133
+ default_factory=lambda: datetime.now(UTC),
134
+ description='Reference point from which ages are measured from',
135
+ )
136
+
137
+ @field_validator('reference_time')
138
+ @classmethod
139
+ def _utc(cls, reference_time: datetime) -> datetime:
140
+ return reference_time if reference_time.tzinfo is not None else reference_time.replace(tzinfo=UTC)
141
+
142
+ def similarity(self, sli_gdf: gpd.GeoDataFrame, osm_provider: OSMProvider) -> np.ndarray:
143
+ self._require(sli_gdf, 'captured_at')
144
+
145
+ captured = pd.to_datetime(sli_gdf['captured_at'], utc=True)
146
+ gap = (pd.Timestamp(self.reference_time) - captured).dt.total_seconds()
147
+ gap = np.abs(gap.to_numpy(dtype='float64', na_value=np.nan)) / SECONDS_PER_YEAR
148
+
149
+ return 1 - np.minimum(gap, self.max_age) / self.max_age
150
+
151
+
152
+ class ProximityCriterion(Criterion):
153
+ kind: Literal['proximity'] = 'proximity'
154
+
155
+ query: str = Field(
156
+ min_length=1,
157
+ description='OSM query of target geometries',
158
+ )
159
+
160
+ max_distance: float = Field(
161
+ gt=0,
162
+ description='Distance, in metres, from which an image is as dissimilar to the ideal image as it gets',
163
+ )
164
+
165
+ time: str = Field(
166
+ default='latest',
167
+ description='Snapshot time for the OSM query',
168
+ )
169
+
170
+ def similarity(self, sli_gdf: gpd.GeoDataFrame, osm_provider: OSMProvider) -> np.ndarray:
171
+ if sli_gdf.crs is None:
172
+ raise ValueError('sli_gdf must have a CRS assigned')
173
+
174
+ utm_crs = sli_gdf.estimate_utm_crs()
175
+ sli_utm = sli_gdf[['geometry']].to_crs(utm_crs).reset_index(drop=True)
176
+
177
+ minx, miny, maxx, maxy = sli_utm.total_bounds
178
+ pad = self.max_distance
179
+ aoi_utm = box(minx - pad, miny - pad, maxx + pad, maxy + pad)
180
+ aoi = gpd.GeoSeries([aoi_utm], crs=utm_crs).to_crs('EPSG:4326').iloc[0]
181
+
182
+ osm_gdf = osm_provider.extract(aoi=aoi, query=self.query, time=self.time)
183
+ if osm_gdf.empty:
184
+ return np.zeros(len(sli_gdf))
185
+
186
+ nearest = gpd.sjoin_nearest(
187
+ sli_utm,
188
+ osm_gdf[['geometry']].to_crs(utm_crs),
189
+ how='left',
190
+ max_distance=self.max_distance,
191
+ distance_col='distance',
192
+ )
193
+ distance = nearest.groupby(level=0)['distance'].min().reindex(sli_utm.index).to_numpy(dtype='float64')
194
+
195
+ return np.nan_to_num(1 - np.clip(distance, 0, self.max_distance) / self.max_distance, nan=0.0)
196
+
197
+
198
+ class ScoreEnricher(Enricher):
199
+ kind: Literal['score'] = 'score'
200
+
201
+ column: str = Field(
202
+ default='score',
203
+ min_length=1,
204
+ description='Name of the metadata entry holding the score',
205
+ )
206
+
207
+ criteria: list[Criterion] = Field(
208
+ min_length=1,
209
+ description='Weighted criteria comparing every image to the ideal one',
210
+ )
211
+
212
+ keep_components: bool = Field(
213
+ default=False,
214
+ description='Also add the similarity of every criterion as `<column>_<criterion label>`',
215
+ )
216
+
217
+ @model_validator(mode='after')
218
+ def unique_labels(self) -> 'ScoreEnricher':
219
+ labels = [criterion.label for criterion in self.criteria]
220
+ if duplicated := sorted({label for label in labels if labels.count(label) > 1}):
221
+ raise ValueError(f'Criteria labels must be unique, repeated ones should have a name: {duplicated}')
222
+
223
+ return self
224
+
225
+ @staticmethod
226
+ def _gower(similarities: np.ndarray, weights: np.ndarray) -> np.ndarray:
227
+ defined = ~np.isnan(similarities)
228
+ total = defined.astype('float64') @ weights
229
+ weighted = np.where(defined, similarities, 0.0) @ weights
230
+ return np.divide(weighted, total, out=np.full(len(similarities), np.nan), where=total > 0)
231
+
232
+ def compute(self, sli_gdf: gpd.GeoDataFrame, osm_provider: OSMProvider) -> pd.DataFrame:
233
+ if sli_gdf.empty:
234
+ similarities = np.empty((0, len(self.criteria)))
235
+ else:
236
+ similarities = [self._similarity(criterion, sli_gdf, osm_provider) for criterion in self.criteria]
237
+ similarities = np.column_stack(similarities)
238
+
239
+ weights = np.array([criterion.weight for criterion in self.criteria], dtype='float64')
240
+ entries = {self.column: self._gower(similarities, weights)}
241
+ if self.keep_components:
242
+ entries |= {
243
+ f'{self.column}_{criterion.label}': similarities[:, i] for i, criterion in enumerate(self.criteria)
244
+ }
245
+
246
+ return pd.DataFrame(entries)
247
+
248
+ @staticmethod
249
+ def _similarity(criterion: Criterion, sli_gdf: gpd.GeoDataFrame, osm_provider: OSMProvider) -> np.ndarray:
250
+ values = np.asarray(criterion.similarity(sli_gdf, osm_provider), dtype='float64')
251
+
252
+ if values.shape != (len(sli_gdf),):
253
+ raise RuntimeError(
254
+ f'{type(criterion).__name__} returned {values.size} similarities for {len(sli_gdf)} images'
255
+ )
256
+
257
+ if (values < 0).any() or (values > 1).any():
258
+ raise RuntimeError(f'{type(criterion).__name__} returned similarities outside [0, 1]')
259
+
260
+ return values
File without changes
@@ -0,0 +1,145 @@
1
+ import logging
2
+ from abc import ABC
3
+ from abc import abstractmethod
4
+ from typing import Literal
5
+
6
+ import geopandas as gpd
7
+ import numpy as np
8
+ import pandas as pd
9
+ import shapely
10
+ from pydantic import BaseModel
11
+ from pydantic import ConfigDict
12
+ from pydantic import Field
13
+
14
+ logger = logging.getLogger(__name__)
15
+
16
+ _PERIOD_FREQ = {
17
+ 'hour': 'h',
18
+ 'day': 'D',
19
+ 'week': 'W',
20
+ 'month': 'M',
21
+ 'year': 'Y',
22
+ }
23
+
24
+
25
+ class SpatialDistributionFilter(BaseModel, ABC):
26
+ model_config = ConfigDict(frozen=True, extra='forbid')
27
+
28
+ @abstractmethod
29
+ def filter(
30
+ self,
31
+ sli_gdf: gpd.GeoDataFrame,
32
+ ) -> gpd.GeoDataFrame:
33
+ """Return the subset of `sli_gdf` matching this filter."""
34
+
35
+
36
+ class SpatialThinning(SpatialDistributionFilter):
37
+ """Thins dense image sequences down to roughly one image per `distance` metres."""
38
+
39
+ kind: Literal['spatial_thinning'] = 'spatial_thinning'
40
+
41
+ distance: float = Field(
42
+ gt=0,
43
+ description='Minimum spacing between retained images, in metres',
44
+ )
45
+
46
+ per_sequence: bool = Field(
47
+ default=False,
48
+ description='Thin each sequence independently instead of across the whole set',
49
+ )
50
+
51
+ def filter(
52
+ self,
53
+ sli_gdf: gpd.GeoDataFrame,
54
+ ) -> gpd.GeoDataFrame:
55
+ if sli_gdf.empty:
56
+ return sli_gdf
57
+
58
+ if sli_gdf.crs is None:
59
+ raise ValueError('sli_gdf must have a CRS assigned')
60
+
61
+ utm_crs = sli_gdf.estimate_utm_crs()
62
+ points = sli_gdf.geometry.to_crs(utm_crs).representative_point()
63
+
64
+ grid = pd.DataFrame(
65
+ {
66
+ 'col': (points.x // self.distance).astype('int64'),
67
+ 'row': (points.y // self.distance).astype('int64'),
68
+ },
69
+ index=sli_gdf.index,
70
+ )
71
+
72
+ if self.per_sequence:
73
+ grid['sequence_id'] = sli_gdf['sequence_id']
74
+ keep = grid.drop_duplicates(subset=['col', 'row', 'sequence_id'], keep='first').index
75
+ else:
76
+ keep = grid.drop_duplicates(subset=['col', 'row'], keep='first').index
77
+
78
+ return sli_gdf.loc[keep]
79
+
80
+
81
+ class ScoreThinning(SpatialDistributionFilter):
82
+ kind: Literal['score_thinning'] = 'score_thinning'
83
+
84
+ distance: float = Field(
85
+ gt=0,
86
+ description='Minimum spacing between retained images, in metres',
87
+ )
88
+
89
+ column: str = Field(
90
+ default='score',
91
+ min_length=1,
92
+ description='Column ranking the images, highest is better',
93
+ )
94
+
95
+ per_sequence: bool = Field(
96
+ default=False,
97
+ description='Only let images of the same sequence suppress each other',
98
+ )
99
+
100
+ def filter(
101
+ self,
102
+ sli_gdf: gpd.GeoDataFrame,
103
+ ) -> gpd.GeoDataFrame:
104
+ if sli_gdf.empty:
105
+ return sli_gdf
106
+
107
+ if sli_gdf.crs is None:
108
+ raise ValueError('sli_gdf must have a CRS assigned')
109
+
110
+ if self.column not in sli_gdf.columns:
111
+ raise ValueError(
112
+ f'sli_gdf must have a {self.column!r} column; '
113
+ f'pass {type(self).__name__} as a selector so it runs after the enricher adding it'
114
+ )
115
+
116
+ if self.per_sequence and 'sequence_id' not in sli_gdf.columns:
117
+ raise ValueError("sli_gdf must have a 'sequence_id' column")
118
+
119
+ count = len(sli_gdf)
120
+ points = sli_gdf.geometry.to_crs(sli_gdf.estimate_utm_crs()).representative_point().to_numpy()
121
+ left, right = shapely.STRtree(points).query(points, predicate='dwithin', distance=self.distance)
122
+
123
+ neighbours = left != right
124
+ if self.per_sequence:
125
+ sequence, _ = pd.factorize(sli_gdf['sequence_id'])
126
+ neighbours &= (sequence[left] == sequence[right]) & (sequence[left] >= 0)
127
+
128
+ left, right = left[neighbours], right[neighbours]
129
+
130
+ grouped = right[np.argsort(left, kind='stable')]
131
+ offsets = np.concatenate([[0], np.cumsum(np.bincount(left, minlength=count))])
132
+
133
+ score = pd.to_numeric(sli_gdf[self.column], errors='coerce').to_numpy(dtype='float64', na_value=np.nan)
134
+ order = np.lexsort((np.arange(count), -np.nan_to_num(score, nan=-np.inf)))
135
+
136
+ suppressed = np.zeros(count, dtype=bool)
137
+ kept = []
138
+ for position in order:
139
+ if suppressed[position]:
140
+ continue
141
+
142
+ kept.append(position)
143
+ suppressed[grouped[offsets[position] : offsets[position + 1]]] = True
144
+
145
+ return sli_gdf.iloc[sorted(kept)]