Skip to content

armgit / ente

Public Imported from GitHub
0

πŸ’š End-to-end encrypted cloud for everything.

[rust] Compute calendar memories in ente-photos

laurensprieme38d5b64405e
diff --git a/rust/crates/photos/src/lib.rs b/rust/crates/photos/src/lib.rs
index 8779e2c117..377197a4ae 100644
--- a/rust/crates/photos/src/lib.rs
+++ b/rust/crates/photos/src/lib.rs
@@ -3,6 +3,7 @@ pub mod db;
pub mod face_clustering;
pub mod files;
pub mod location;
+pub mod memories;
pub mod metadata;
pub mod ml_db;
pub mod ml_store;
diff --git a/rust/crates/photos/src/memories/calendar.rs b/rust/crates/photos/src/memories/calendar.rs
new file mode 100644
index 0000000000..8f62ef855e
--- /dev/null
+++ b/rust/crates/photos/src/memories/calendar.rs
@@ -0,0 +1,155 @@
+pub(super) const MICROS_PER_SECOND: i64 = 1_000_000;
+pub(super) const MICROS_PER_MINUTE: i64 = 60 * MICROS_PER_SECOND;
+pub(super) const MICROS_PER_DAY: i64 = 24 * 60 * MICROS_PER_MINUTE;
+
+const DAYS_PER_ERA: i64 = 146_097;
+const DAYS_FROM_ERA_START_TO_UNIX_EPOCH: i64 = 719_468;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct LocalDate {
+ pub year: i32,
+ pub month: i32,
+ pub day: i32,
+}
+
+impl LocalDate {
+ pub(super) fn new(year: i32, month: i32, day: i32) -> Self {
+ let months = i64::from(year) * 12 + i64::from(month) - 1;
+ let first_of_month = Self {
+ year: months.div_euclid(12) as i32,
+ month: months.rem_euclid(12) as i32 + 1,
+ day: 1,
+ };
+ first_of_month.plus_days(i64::from(day) - 1)
+ }
+
+ pub(super) fn from_days(days_since_epoch: i64) -> Self {
+ let days = days_since_epoch + DAYS_FROM_ERA_START_TO_UNIX_EPOCH;
+ let era = days.div_euclid(DAYS_PER_ERA);
+ let day_of_era = days.rem_euclid(DAYS_PER_ERA);
+ let year_of_era =
+ (day_of_era - day_of_era / 1460 + day_of_era / 36_524 - day_of_era / 146_096) / 365;
+ let day_of_year = day_of_era - (365 * year_of_era + year_of_era / 4 - year_of_era / 100);
+ let shifted_month = (5 * day_of_year + 2) / 153;
+ let day = day_of_year - (153 * shifted_month + 2) / 5 + 1;
+ let month = if shifted_month < 10 {
+ shifted_month + 3
+ } else {
+ shifted_month - 9
+ };
+ Self {
+ year: (era * 400 + year_of_era + i64::from(month <= 2)) as i32,
+ month: month as i32,
+ day: day as i32,
+ }
+ }
+
+ pub(super) fn days_since_epoch(self) -> i64 {
+ let year = i64::from(self.year) - i64::from(self.month <= 2);
+ let era = year.div_euclid(400);
+ let year_of_era = year.rem_euclid(400);
+ let month = i64::from(self.month);
+ let shifted_month = if month > 2 { month - 3 } else { month + 9 };
+ let day_of_year = (153 * shifted_month + 2) / 5 + i64::from(self.day) - 1;
+ let day_of_era = year_of_era * 365 + year_of_era / 4 - year_of_era / 100 + day_of_year;
+ era * DAYS_PER_ERA + day_of_era - DAYS_FROM_ERA_START_TO_UNIX_EPOCH
+ }
+
+ pub(super) fn of_local_time(local_micros: i64) -> Self {
+ Self::from_days(local_micros.div_euclid(MICROS_PER_DAY))
+ }
+
+ pub(super) fn plus_days(self, days: i64) -> Self {
+ Self::from_days(self.days_since_epoch() + days)
+ }
+
+ pub(super) fn days_until(self, other: Self) -> i64 {
+ other.days_since_epoch() - self.days_since_epoch()
+ }
+
+ pub(super) fn weekday(self) -> i64 {
+ (self.days_since_epoch() + 3).rem_euclid(7) + 1
+ }
+
+ pub(super) fn week_of_year(self) -> i64 {
+ Self::new(self.year, 1, 1).days_until(self) / 7 + 1
+ }
+
+ pub(super) fn is_in_leap_year(self) -> bool {
+ self.year % 4 == 0 && (self.year % 100 != 0 || self.year % 400 == 0)
+ }
+}
+
+pub(super) struct Anniversary {
+ pub(super) days_from_today: i64,
+ pub(super) years_ago: i32,
+}
+
+pub(super) fn upcoming_anniversary(
+ date: LocalDate,
+ today: LocalDate,
+ window_days: i64,
+) -> Option<Anniversary> {
+ [today.year, today.year + 1].into_iter().find_map(|year| {
+ let days_from_today = today.days_until(LocalDate::new(year, date.month, date.day));
+ (0..window_days)
+ .contains(&days_from_today)
+ .then_some(Anniversary {
+ days_from_today,
+ years_ago: year - date.year,
+ })
+ })
+}
+
+#[cfg(test)]
+mod tests {
+ use super::{LocalDate, upcoming_anniversary};
+
+ fn date(year: i32, month: i32, day: i32) -> LocalDate {
+ LocalDate { year, month, day }
+ }
+
+ #[test]
+ fn days_round_trip_across_centuries_and_before_the_epoch() {
+ for (value, days) in [
+ (date(1970, 1, 1), 0),
+ (date(1969, 12, 31), -1),
+ (date(2000, 2, 29), 11_016),
+ (date(1900, 3, 1), -25_508),
+ (date(2400, 12, 31), 157_419),
+ ] {
+ assert_eq!(value.days_since_epoch(), days, "{value:?}");
+ assert_eq!(LocalDate::from_days(days), value);
+ }
+ }
+
+ #[test]
+ fn new_rolls_overflowing_months_and_days_like_dart() {
+ assert_eq!(LocalDate::new(2025, 13, 1), date(2026, 1, 1));
+ assert_eq!(LocalDate::new(2025, 0, 1), date(2024, 12, 1));
+ assert_eq!(LocalDate::new(2024, 3, 0), date(2024, 2, 29));
+ assert_eq!(LocalDate::new(2025, 2, 29), date(2025, 3, 1));
+ assert_eq!(LocalDate::new(2025, 1, 32), date(2025, 2, 1));
+ }
+
+ #[test]
+ fn weeks_are_seven_day_blocks_from_january_first() {
+ assert_eq!(date(2026, 10, 26).weekday(), 1);
+ assert_eq!(date(2026, 11, 1).weekday(), 7);
+ assert_eq!(date(2026, 1, 7).week_of_year(), 1);
+ assert_eq!(date(2026, 1, 8).week_of_year(), 2);
+ assert_eq!(date(2024, 12, 30).week_of_year(), 53);
+ }
+
+ #[test]
+ fn anniversaries_cross_the_year_end_and_move_leap_days_to_march_first() {
+ let new_year = upcoming_anniversary(date(2020, 1, 1), date(2025, 12, 31), 3).unwrap();
+ assert_eq!((new_year.days_from_today, new_year.years_ago), (1, 6));
+
+ let leap_day = upcoming_anniversary(date(2024, 2, 29), date(2025, 2, 28), 3).unwrap();
+ assert_eq!((leap_day.days_from_today, leap_day.years_ago), (1, 1));
+
+ assert!(upcoming_anniversary(date(2020, 10, 26), date(2026, 10, 28), 3).is_none());
+ assert!(upcoming_anniversary(date(2020, 11, 1), date(2026, 10, 29), 3).is_none());
+ }
+}
diff --git a/rust/crates/photos/src/memories/filler.rs b/rust/crates/photos/src/memories/filler.rs
new file mode 100644
index 0000000000..d0e259df7a
--- /dev/null
+++ b/rust/crates/photos/src/memories/filler.rs
@@ -0,0 +1,83 @@
+use std::collections::BTreeMap;
+
+use super::UPDATE_FREQUENCY_DAYS;
+use super::calendar::{MICROS_PER_DAY, upcoming_anniversary};
+use super::input::Period;
+use super::output::{Memory, MemoryKind};
+use super::photo::Photo;
+
+const MAXIMUM_YEARS_AGO: i32 = 30;
+const MINIMUM_AGE_DAYS: i64 = 364 - UPDATE_FREQUENCY_DAYS;
+
+pub(super) fn memories(photos: &[&Photo], period: Period) -> Vec<Memory> {
+ let today = period.today();
+ let cutoff = period.now - MINIMUM_AGE_DAYS * MICROS_PER_DAY;
+ let mut photos_by_years_ago: BTreeMap<i32, Vec<&Photo>> = BTreeMap::new();
+ for &photo in photos {
+ if photo.creation_time <= cutoff
+ && let Some(anniversary) =
+ upcoming_anniversary(photo.date, today, UPDATE_FREQUENCY_DAYS)
+ && (1..=MAXIMUM_YEARS_AGO).contains(&anniversary.years_ago)
+ {
+ photos_by_years_ago
+ .entry(anniversary.years_ago)
+ .or_default()
+ .push(photo);
+ }
+ }
+ photos_by_years_ago
+ .into_iter()
+ .map(|(years_ago, photos)| {
+ Memory::new(
+ MemoryKind::Filler { years_ago },
+ &photos,
+ period.now,
+ period.now + UPDATE_FREQUENCY_DAYS * MICROS_PER_DAY,
+ )
+ })
+ .collect()
+}
+
+#[cfg(test)]
+mod tests {
+ use super::memories;
+ use crate::memories::output::MemoryKind;
+ use crate::memories::photo::prepare;
+ use crate::memories::tests::{file, files_on, micros, period};
+
+ #[test]
+ fn groups_anniversaries_of_the_next_three_days_by_years_ago() {
+ let mut files = files_on(1, "2025-10-31", 2);
+ files.extend(files_on(10, "2024-10-29", 1));
+ files.extend(files_on(20, "2023-10-30", 1));
+ files.extend(files_on(30, "2025-11-01", 1));
+ files.extend(files_on(40, "1990-10-29", 1));
+ files.extend(files_on(50, "2026-10-29", 1));
+ files.push(file(60, "2023-10-30T07:00:00"));
+ let mut recently_created = file(70, "2026-10-20T08:00:00");
+ recently_created.local_date_time = Some("2024-10-30T08:00:00".to_owned());
+ files.push(recently_created);
+ let photos = prepare(&files);
+ let photos: Vec<_> = photos.iter().collect();
+
+ let memories = memories(&photos, period("2026-10-29T18:00:00"));
+
+ let groups: Vec<(MemoryKind, Vec<i64>)> = memories
+ .iter()
+ .map(|memory| (memory.kind, memory.file_ids.clone()))
+ .collect();
+ assert_eq!(
+ groups,
+ [
+ (MemoryKind::Filler { years_ago: 1 }, vec![1, 2]),
+ (MemoryKind::Filler { years_ago: 2 }, vec![10]),
+ (MemoryKind::Filler { years_ago: 3 }, vec![60, 20]),
+ ]
+ );
+ assert_eq!(
+ memories[0].first_date_to_show,
+ micros("2026-10-29T18:00:00")
+ );
+ assert_eq!(memories[0].last_date_to_show, micros("2026-11-01T18:00:00"));
+ }
+}
diff --git a/rust/crates/photos/src/memories/input.rs b/rust/crates/photos/src/memories/input.rs
new file mode 100644
index 0000000000..28c88b9e8b
--- /dev/null
+++ b/rust/crates/photos/src/memories/input.rs
@@ -0,0 +1,47 @@
+use super::calendar::{LocalDate, MICROS_PER_DAY, MICROS_PER_SECOND};
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct MemoryFile {
+ pub id: i64,
+ pub creation_time: i64,
+ pub local_date_time: Option<String>,
+ pub utc_offset_seconds: i32,
+ pub collection_id: Option<i64>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct MemoriesRequest {
+ pub files: Vec<MemoryFile>,
+ pub excluded_collection_ids: Vec<i64>,
+ pub seed: u64,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct Period {
+ pub now: i64,
+ pub utc_offset_seconds: i32,
+}
+
+impl Period {
+ fn local_now(self) -> i64 {
+ self.now + self.utc_offset_micros()
+ }
+
+ pub(super) fn today(self) -> LocalDate {
+ LocalDate::of_local_time(self.local_now())
+ }
+
+ pub(super) fn start_of(self, date: LocalDate) -> i64 {
+ date.days_since_epoch() * MICROS_PER_DAY - self.utc_offset_micros()
+ }
+
+ fn utc_offset_micros(self) -> i64 {
+ i64::from(self.utc_offset_seconds) * MICROS_PER_SECOND
+ }
+}
+
+pub trait PhotoSignals {
+ fn face_weight(&self, file_id: i64) -> u32;
+ fn nostalgia(&self, file_id: i64) -> Option<f32>;
+ fn similarity(&self, file_id: i64, other_file_id: i64) -> Option<f32>;
+}
diff --git a/rust/crates/photos/src/memories/mod.rs b/rust/crates/photos/src/memories/mod.rs
new file mode 100644
index 0000000000..8e8fa294c3
--- /dev/null
+++ b/rust/crates/photos/src/memories/mod.rs
@@ -0,0 +1,230 @@
+mod calendar;
+mod filler;
+mod input;
+mod on_this_day;
+mod output;
+mod photo;
+mod rng;
+mod selector;
+mod time;
+
+use std::collections::HashSet;
+
+pub use calendar::LocalDate;
+pub use input::{MemoriesRequest, MemoryFile, Period, PhotoSignals};
+pub use output::{Memory, MemoryKind, TimeMemory};
+
+use photo::Photo;
+use selector::Selector;
+
+const UPDATE_FREQUENCY_DAYS: i64 = 3;
+const MAX_MEMORY_ITEMS: usize = 100;
+const MINIMUM_MEMORY_LENGTH: usize = 5;
+
+pub fn compute_smart_memories(
+ request: &MemoriesRequest,
+ periods: &[Period],
+ signals: Option<&dyn PhotoSignals>,
+) -> Vec<Vec<Memory>> {
+ let photos = photo::prepare(&request.files);
+ let excluded_collection_ids: HashSet<i64> =
+ request.excluded_collection_ids.iter().copied().collect();
+ let mut selector = Selector::new(signals, request.seed);
+ periods
+ .iter()
+ .map(|&period| {
+ let mut memories =
+ on_this_day::memories(&photos, period, &excluded_collection_ids, &mut selector);
+ let time_memories = time::memories(
+ &unused_photos(&photos, &memories),
+ &photos,
+ period,
+ &mut selector,
+ );
+ memories.extend(time_memories);
+ let filler_memories = filler::memories(&unused_photos(&photos, &memories), period);
+ memories.extend(filler_memories);
+ memories
+ })
+ .collect()
+}
+
+pub fn compute_simple_memories(request: &MemoriesRequest, period: Period) -> Vec<Memory> {
+ let photos = photo::prepare(&request.files);
+ let excluded_collection_ids: HashSet<i64> =
+ request.excluded_collection_ids.iter().copied().collect();
+ let mut selector = Selector::new(None, request.seed);
+ let mut memories: Vec<Memory> =
+ on_this_day::memories(&photos, period, &excluded_collection_ids, &mut selector)
+ .into_iter()
+ .take(1)
+ .filter(|memory| memory.is_shown_at(period.now))
+ .collect();
+ let filler_memories = filler::memories(&unused_photos(&photos, &memories), period);
+ memories.extend(filler_memories);
+ memories
+}
+
+fn unused_photos<'p>(
+ photos: impl IntoIterator<Item = &'p Photo>,
+ memories: &[Memory],
+) -> Vec<&'p Photo> {
+ let used: HashSet<i64> = memories
+ .iter()
+ .flat_map(|memory| memory.file_ids.iter().copied())
+ .collect();
+ photos
+ .into_iter()
+ .filter(|photo| !used.contains(&photo.id))
+ .collect()
+}
+
+#[cfg(test)]
+mod tests {
+ use ente_exif::DateTime;
+
+ use super::{
+ MemoriesRequest, Memory, MemoryFile, MemoryKind, Period, TimeMemory,
+ compute_simple_memories, compute_smart_memories,
+ };
+
+ pub(super) fn micros(date_time: &str) -> i64 {
+ DateTime::parse(&format!("{date_time}Z"))
+ .and_then(DateTime::unix_micros)
+ .unwrap()
+ }
+
+ pub(super) fn file(id: i64, date_time: &str) -> MemoryFile {
+ MemoryFile {
+ id,
+ creation_time: micros(date_time),
+ local_date_time: None,
+ utc_offset_seconds: 0,
+ collection_id: None,
+ }
+ }
+
+ pub(super) fn files_on(first_id: i64, date: &str, count: i64) -> Vec<MemoryFile> {
+ (0..count)
+ .map(|index| {
+ let minutes = 8 * 60 + index * 20;
+ file(
+ first_id + index,
+ &format!("{date}T{:02}:{:02}:00", minutes / 60, minutes % 60),
+ )
+ })
+ .collect()
+ }
+
+ pub(super) fn period(date_time: &str) -> Period {
+ Period {
+ now: micros(date_time),
+ utc_offset_seconds: 0,
+ }
+ }
+
+ fn kinds(memories: &[Memory]) -> Vec<MemoryKind> {
+ memories.iter().map(|memory| memory.kind).collect()
+ }
+
+ fn library() -> Vec<MemoryFile> {
+ let background_start = micros("2019-03-01T00:00:00");
+ let mut files: Vec<MemoryFile> = (0..1500)
+ .map(|index| MemoryFile {
+ creation_time: background_start + index * 20 * 60_000_000,
+ ..file(1000 + index, "2019-03-01T00:00:00")
+ })
+ .collect();
+ files.extend(files_on(1, "2023-10-30", 3));
+ files.extend(files_on(10, "2021-10-30", 3));
+ files.extend(files_on(20, "2024-11-01", 1));
+ files.extend(files_on(30, "2026-10-20", 6));
+ files
+ }
+
+ fn request() -> MemoriesRequest {
+ MemoriesRequest {
+ files: library(),
+ excluded_collection_ids: Vec::new(),
+ seed: 3,
+ }
+ }
+
+ #[test]
+ fn each_period_runs_on_this_day_then_time_then_fillers_without_reusing_photos() {
+ let periods = compute_smart_memories(
+ &request(),
+ &[period("2026-10-30T09:00:00"), period("2026-11-02T09:00:00")],
+ None,
+ );
+
+ let current = &periods[0];
+ assert_eq!(
+ kinds(current),
+ [
+ MemoryKind::OnThisDay,
+ MemoryKind::Time(TimeMemory::LastWeek),
+ MemoryKind::Filler { years_ago: 2 },
+ ]
+ );
+ assert_eq!(current[0].file_ids, [10, 11, 12, 1, 2, 3]);
+ assert_eq!(current[1].file_ids, [30, 31, 32, 33, 34, 35]);
+ assert_eq!(current[2].file_ids, [20]);
+
+ let next = &periods[1];
+ assert_eq!(
+ kinds(next),
+ [
+ MemoryKind::Time(TimeMemory::LastMonth),
+ MemoryKind::Time(TimeMemory::Week { years_ago: Some(3) }),
+ MemoryKind::Time(TimeMemory::Week { years_ago: Some(5) }),
+ MemoryKind::Time(TimeMemory::Month {
+ year: 2024,
+ month: 11,
+ years_ago: Some(2),
+ }),
+ ]
+ );
+ assert_eq!(next[0].first_date_to_show, micros("2026-11-01T00:00:00"));
+ assert_eq!(next[0].last_date_to_show, micros("2026-12-01T00:00:00"));
+ }
+
+ #[test]
+ fn simple_memories_keep_on_this_day_only_when_it_shows_today() {
+ let today = compute_simple_memories(&request(), period("2026-10-30T09:00:00"));
+ assert_eq!(
+ kinds(&today),
+ [MemoryKind::OnThisDay, MemoryKind::Filler { years_ago: 2 }]
+ );
+
+ let day_before = compute_simple_memories(&request(), period("2026-10-29T09:00:00"));
+ assert_eq!(
+ kinds(&day_before),
+ [
+ MemoryKind::Filler { years_ago: 3 },
+ MemoryKind::Filler { years_ago: 5 },
+ ]
+ );
+ }
+
+ #[test]
+ fn memories_hold_at_most_one_hundred_photos() {
+ let request = MemoriesRequest {
+ files: (0..150)
+ .map(|index| {
+ file(
+ index,
+ &format!("2020-10-29T{:02}:{:02}:00", index / 60, index % 60),
+ )
+ })
+ .collect(),
+ excluded_collection_ids: Vec::new(),
+ seed: 0,
+ };
+
+ let memories = compute_simple_memories(&request, period("2026-10-28T09:00:00"));
+
+ assert_eq!(kinds(&memories), [MemoryKind::Filler { years_ago: 6 }]);
+ assert_eq!(memories[0].file_ids, (0..100).collect::<Vec<_>>());
+ }
+}
diff --git a/rust/crates/photos/src/memories/on_this_day.rs b/rust/crates/photos/src/memories/on_this_day.rs
new file mode 100644
index 0000000000..090942da87
--- /dev/null
+++ b/rust/crates/photos/src/memories/on_this_day.rs
@@ -0,0 +1,151 @@
+use std::collections::{BTreeMap, HashSet};
+
+use super::UPDATE_FREQUENCY_DAYS;
+use super::calendar::{MICROS_PER_DAY, upcoming_anniversary};
+use super::input::Period;
+use super::output::{Memory, MemoryKind};
+use super::photo::Photo;
+use super::selector::Selector;
+
+const MINIMUM_PHOTOS: usize = 5;
+const MINIMUM_YEARS: usize = 2;
+const MAXIMUM_PHOTOS: usize = 20;
+const MINIMUM_AGE_DAYS: i64 = 363 - UPDATE_FREQUENCY_DAYS;
+
+pub(super) fn memories(
+ photos: &[Photo],
+ period: Period,
+ excluded_collection_ids: &HashSet<i64>,
+ selector: &mut Selector,
+) -> Vec<Memory> {
+ let today = period.today();
+ let cutoff = period.start_of(today) - MINIMUM_AGE_DAYS * MICROS_PER_DAY;
+ let mut photos_by_day: BTreeMap<i64, Vec<&Photo>> = BTreeMap::new();
+ for photo in photos {
+ if photo.creation_time > cutoff
+ || photo
+ .collection_id
+ .is_some_and(|id| excluded_collection_ids.contains(&id))
+ {
+ continue;
+ }
+ if let Some(anniversary) = upcoming_anniversary(photo.date, today, UPDATE_FREQUENCY_DAYS)
+ && anniversary.years_ago >= 1
+ {
+ photos_by_day
+ .entry(anniversary.days_from_today)
+ .or_default()
+ .push(photo);
+ }
+ }
+ photos_by_day
+ .into_iter()
+ .filter(|(_, photos)| {
+ photos.len() >= MINIMUM_PHOTOS
+ && photos
+ .iter()
+ .map(|photo| photo.date.year)
+ .collect::<HashSet<_>>()
+ .len()
+ >= MINIMUM_YEARS
+ })
+ .map(|(days_from_today, photos)| {
+ let day = today.plus_days(days_from_today);
+ Memory::new(
+ MemoryKind::OnThisDay,
+ &selector.sample_across_years(photos, MAXIMUM_PHOTOS),
+ period.start_of(day),
+ period.start_of(day.plus_days(1)),
+ )
+ })
+ .collect()
+}
+
+#[cfg(test)]
+mod tests {
+ use std::collections::HashSet;
+
+ use super::memories;
+ use crate::memories::input::MemoryFile;
+ use crate::memories::output::{Memory, MemoryKind};
+ use crate::memories::photo::prepare;
+ use crate::memories::selector::Selector;
+ use crate::memories::tests::{files_on, micros, period};
+
+ fn on_this_day(files: &[MemoryFile], now: &str, excluded: &[i64]) -> Vec<Memory> {
+ let photos = prepare(files);
+ memories(
+ &photos,
+ period(now),
+ &excluded.iter().copied().collect::<HashSet<_>>(),
+ &mut Selector::new(None, 1),
+ )
+ }
+
+ #[test]
+ fn shows_each_of_the_next_three_days_with_five_photos_from_two_earlier_years() {
+ let mut files = files_on(1, "2023-10-30", 3);
+ files.extend(files_on(10, "2021-10-30", 2));
+ files.extend(files_on(20, "2024-10-29", 4));
+ files.extend(files_on(30, "2026-10-31", 5));
+ files.extend(files_on(40, "2022-11-01", 3));
+ files.extend(files_on(50, "2020-11-01", 3));
+
+ let memories = on_this_day(&files, "2026-10-29T18:00:00", &[]);
+
+ assert_eq!(memories.len(), 1);
+ assert_eq!(memories[0].kind, MemoryKind::OnThisDay);
+ assert_eq!(memories[0].file_ids, [10, 11, 1, 2, 3]);
+ assert_eq!(
+ memories[0].first_date_to_show,
+ micros("2026-10-30T00:00:00")
+ );
+ assert_eq!(memories[0].last_date_to_show, micros("2026-10-31T00:00:00"));
+ }
+
+ #[test]
+ fn skips_photos_created_within_the_last_year_whatever_their_dates() {
+ let mut files = files_on(1, "2026-10-28", 5);
+ for (index, file) in files.iter_mut().enumerate() {
+ let year = if index < 3 { 2021 } else { 2023 };
+ file.local_date_time = Some(format!("{year}-10-29T08:00:00"));
+ }
+
+ assert!(on_this_day(&files, "2026-10-29T08:00:00", &[]).is_empty());
+ }
+
+ #[test]
+ fn skips_photos_in_excluded_collections() {
+ let mut files = files_on(1, "2023-10-29", 3);
+ files.extend(files_on(10, "2021-10-29", 2));
+ files[0].collection_id = Some(7);
+
+ assert!(on_this_day(&files, "2026-10-29T08:00:00", &[7]).is_empty());
+ assert_eq!(on_this_day(&files, "2026-10-29T08:00:00", &[]).len(), 1);
+ }
+
+ #[test]
+ fn large_days_keep_twenty_photos_spread_across_years() {
+ let mut files = Vec::new();
+ for year in 2001..2004 {
+ files.extend(files_on(
+ i64::from(year) * 100,
+ &format!("{year}-10-29"),
+ 30,
+ ));
+ }
+
+ let memories = on_this_day(&files, "2026-10-29T08:00:00", &[]);
+
+ let ids = &memories[0].file_ids;
+ assert_eq!(ids.len(), 20);
+ for year in 2001..2004 {
+ let from_year = ids
+ .iter()
+ .filter(|id| **id / 100 == i64::from(year))
+ .count();
+ assert!((6..=7).contains(&from_year), "{year}: {from_year}");
+ }
+ assert!(ids.windows(2).all(|pair| pair[0] < pair[1]));
+ }
+}
diff --git a/rust/crates/photos/src/memories/output.rs b/rust/crates/photos/src/memories/output.rs
new file mode 100644
index 0000000000..499003a21a
--- /dev/null
+++ b/rust/crates/photos/src/memories/output.rs
@@ -0,0 +1,60 @@
+use super::MAX_MEMORY_ITEMS;
+use super::calendar::LocalDate;
+use super::photo::Photo;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Memory {
+ pub kind: MemoryKind,
+ pub file_ids: Vec<i64>,
+ pub first_date_to_show: i64,
+ pub last_date_to_show: i64,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum MemoryKind {
+ OnThisDay,
+ Time(TimeMemory),
+ Filler { years_ago: i32 },
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum TimeMemory {
+ Day {
+ date: LocalDate,
+ years_ago: Option<i32>,
+ },
+ Week {
+ years_ago: Option<i32>,
+ },
+ Month {
+ year: i32,
+ month: i32,
+ years_ago: Option<i32>,
+ },
+ LastWeek,
+ LastMonth,
+}
+
+impl Memory {
+ pub(super) fn new(
+ kind: MemoryKind,
+ photos: &[&Photo],
+ first_date_to_show: i64,
+ last_date_to_show: i64,
+ ) -> Self {
+ Self {
+ kind,
+ file_ids: photos
+ .iter()
+ .take(MAX_MEMORY_ITEMS)
+ .map(|photo| photo.id)
+ .collect(),
+ first_date_to_show,
+ last_date_to_show,
+ }
+ }
+
+ pub(super) fn is_shown_at(&self, time: i64) -> bool {
+ (self.first_date_to_show..=self.last_date_to_show).contains(&time)
+ }
+}
diff --git a/rust/crates/photos/src/memories/photo.rs b/rust/crates/photos/src/memories/photo.rs
new file mode 100644
index 0000000000..dc7bd8d827
--- /dev/null
+++ b/rust/crates/photos/src/memories/photo.rs
@@ -0,0 +1,95 @@
+use ente_exif::DateTime;
+
+use super::calendar::{LocalDate, MICROS_PER_SECOND};
+use super::input::MemoryFile;
+
+#[derive(Debug)]
+pub(super) struct Photo {
+ pub(super) id: i64,
+ pub(super) creation_time: i64,
+ pub(super) date: LocalDate,
+ pub(super) collection_id: Option<i64>,
+}
+
+pub(super) fn prepare(files: &[MemoryFile]) -> Vec<Photo> {
+ let mut photos: Vec<Photo> = files.iter().map(Photo::new).collect();
+ photos.sort_by_key(|photo| (photo.creation_time, photo.id));
+ photos
+}
+
+pub(super) fn sort_chronologically(photos: &mut [&Photo]) {
+ photos.sort_by_key(|photo| (photo.creation_time, photo.id));
+}
+
+impl Photo {
+ fn new(file: &MemoryFile) -> Self {
+ let local_time = file
+ .local_date_time
+ .as_deref()
+ .and_then(wall_clock_micros)
+ .unwrap_or(file.creation_time + i64::from(file.utc_offset_seconds) * MICROS_PER_SECOND);
+ Self {
+ id: file.id,
+ creation_time: file.creation_time,
+ date: LocalDate::of_local_time(local_time),
+ collection_id: file.collection_id,
+ }
+ }
+}
+
+fn wall_clock_micros(date_time: &str) -> Option<i64> {
+ DateTime {
+ offset_minutes: Some(0),
+ ..DateTime::parse(date_time)?
+ }
+ .unix_micros()
+}
+
+#[cfg(test)]
+mod tests {
+ use super::prepare;
+ use crate::memories::calendar::LocalDate;
+ use crate::memories::tests::{file, micros};
+
+ #[test]
+ fn local_dates_prefer_the_capture_wall_clock_and_fall_back_to_the_device_offset() {
+ let creation_time = micros("2024-03-10T23:30:00");
+ let with_wall_clock = |local_date_time: &str| {
+ let mut photo = file(1, "2024-03-10T23:30:00");
+ photo.local_date_time = Some(local_date_time.to_owned());
+ photo.utc_offset_seconds = 3600;
+ prepare(&[photo]).remove(0)
+ };
+
+ let tokyo = with_wall_clock("2024-03-11T08:30:00.000");
+ assert_eq!(tokyo.date, LocalDate::new(2024, 3, 11));
+ assert_eq!(tokyo.creation_time, creation_time);
+
+ assert_eq!(
+ with_wall_clock("2024-03-10T18:30:00-05:00").date,
+ LocalDate::new(2024, 3, 10)
+ );
+ assert_eq!(
+ with_wall_clock("not a date").date,
+ LocalDate::new(2024, 3, 11)
+ );
+
+ let mut without_wall_clock = file(2, "2024-03-10T23:30:00");
+ without_wall_clock.utc_offset_seconds = -3600;
+ assert_eq!(
+ prepare(&[without_wall_clock])[0].date,
+ LocalDate::new(2024, 3, 10)
+ );
+ }
+
+ #[test]
+ fn photos_are_ordered_by_creation_time_then_id() {
+ let photos = prepare(&[
+ file(3, "2024-01-02T00:00:00"),
+ file(2, "2024-01-01T00:00:00"),
+ file(1, "2024-01-02T00:00:00"),
+ ]);
+ let ids: Vec<i64> = photos.iter().map(|photo| photo.id).collect();
+ assert_eq!(ids, [2, 1, 3]);
+ }
+}
diff --git a/rust/crates/photos/src/memories/rng.rs b/rust/crates/photos/src/memories/rng.rs
new file mode 100644
index 0000000000..492cd91178
--- /dev/null
+++ b/rust/crates/photos/src/memories/rng.rs
@@ -0,0 +1,48 @@
+pub(super) struct Rng {
+ state: u64,
+}
+
+impl Rng {
+ pub(super) fn new(seed: u64) -> Self {
+ Self { state: seed }
+ }
+
+ pub(super) fn shuffle<T>(&mut self, items: &mut [T]) {
+ for index in (1..items.len()).rev() {
+ items.swap(index, self.below(index + 1));
+ }
+ }
+
+ fn below(&mut self, bound: usize) -> usize {
+ ((u128::from(self.next_u64()) * bound as u128) >> 64) as usize
+ }
+
+ fn next_u64(&mut self) -> u64 {
+ self.state = self.state.wrapping_add(0x9E37_79B9_7F4A_7C15);
+ let mut value = self.state;
+ value = (value ^ (value >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
+ value = (value ^ (value >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
+ value ^ (value >> 31)
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::Rng;
+
+ fn shuffled(seed: u64) -> Vec<u32> {
+ let mut items: Vec<u32> = (0..50).collect();
+ Rng::new(seed).shuffle(&mut items);
+ items
+ }
+
+ #[test]
+ fn shuffles_are_permutations_determined_by_the_seed() {
+ let first = shuffled(7);
+ let mut sorted = first.clone();
+ sorted.sort_unstable();
+ assert_eq!(sorted, (0..50).collect::<Vec<_>>());
+ assert_eq!(first, shuffled(7));
+ assert_ne!(first, shuffled(8));
+ }
+}
diff --git a/rust/crates/photos/src/memories/selector.rs b/rust/crates/photos/src/memories/selector.rs
new file mode 100644
index 0000000000..69f676742c
--- /dev/null
+++ b/rust/crates/photos/src/memories/selector.rs
@@ -0,0 +1,486 @@
+use std::collections::{BTreeMap, HashSet};
+
+use super::calendar::MICROS_PER_MINUTE;
+use super::input::PhotoSignals;
+use super::photo::{Photo, sort_chronologically};
+use super::rng::Rng;
+
+const DEFAULT_SELECTION_SIZE: usize = 10;
+const MINIMUM_TIME_GAP: i64 = 10 * MICROS_PER_MINUTE;
+const NEAR_DUPLICATE_SIMILARITY: f32 = 0.80;
+const FACE_WEIGHT_SCORE: f64 = 1000.0;
+
+pub(super) struct Selector<'s> {
+ signals: Option<&'s dyn PhotoSignals>,
+ rng: Rng,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum Spread {
+ None,
+ OverTime,
+ AcrossYears,
+}
+
+#[derive(Clone, Copy)]
+struct Candidate<'p> {
+ photo: &'p Photo,
+ score: f64,
+}
+
+impl<'s> Selector<'s> {
+ pub(super) fn new(signals: Option<&'s dyn PhotoSignals>, seed: u64) -> Self {
+ Self {
+ signals,
+ rng: Rng::new(seed),
+ }
+ }
+
+ pub(super) fn best<'p>(
+ &mut self,
+ photos: Vec<&'p Photo>,
+ preferred_size: Option<usize>,
+ ) -> Vec<&'p Photo> {
+ self.select(photos, preferred_size, false)
+ }
+
+ pub(super) fn best_over_time<'p>(
+ &mut self,
+ photos: Vec<&'p Photo>,
+ size: usize,
+ ) -> Vec<&'p Photo> {
+ self.select(photos, Some(size), true)
+ }
+
+ pub(super) fn sample_across_years<'p>(
+ &mut self,
+ mut photos: Vec<&'p Photo>,
+ size: usize,
+ ) -> Vec<&'p Photo> {
+ sort_chronologically(&mut photos);
+ if photos.len() <= size {
+ return photos;
+ }
+ let mut years: Vec<Vec<&Photo>> = by_year(&photos).into_values().collect();
+ for year in &mut years {
+ self.rng.shuffle(year);
+ }
+ if years.len() > size {
+ self.rng.shuffle(&mut years);
+ years.truncate(size);
+ years.sort_by_key(|year| year[0].date.year);
+ }
+ let mut selected = round_robin(&years, size, |_, _, _| true);
+ sort_chronologically(&mut selected);
+ selected
+ }
+
+ fn select<'p>(
+ &mut self,
+ mut photos: Vec<&'p Photo>,
+ preferred_size: Option<usize>,
+ over_time: bool,
+ ) -> Vec<&'p Photo> {
+ sort_chronologically(&mut photos);
+ let mut size = preferred_size.unwrap_or(DEFAULT_SELECTION_SIZE);
+ if photos.len() <= size {
+ return photos;
+ }
+ let year_count = photos
+ .iter()
+ .map(|photo| photo.date.year)
+ .collect::<HashSet<_>>()
+ .len();
+ let spread = if over_time {
+ Spread::OverTime
+ } else if year_count <= 1 {
+ Spread::None
+ } else {
+ if (preferred_size.is_none() || self.signals.is_none())
+ && year_count * 2 > DEFAULT_SELECTION_SIZE
+ {
+ size = year_count * 3;
+ if photos.len() < size {
+ return photos;
+ }
+ }
+ Spread::AcrossYears
+ };
+ let mut selected = match self.signals {
+ Some(signals) => ranked(&photos, size, spread, signals),
+ None => self.random(&photos, size, spread),
+ };
+ sort_chronologically(&mut selected);
+ selected
+ }
+
+ fn random<'p>(&mut self, photos: &[&'p Photo], size: usize, spread: Spread) -> Vec<&'p Photo> {
+ if spread != Spread::AcrossYears {
+ return self.random_over_time(photos, size);
+ }
+ let mut years: Vec<Vec<&Photo>> = by_year(photos).into_values().rev().collect();
+ for year in &mut years {
+ self.rng.shuffle(year);
+ }
+ round_robin(&years, size, |_, photo, selected| {
+ !is_too_close(photo, selected)
+ })
+ }
+
+ fn random_over_time<'p>(&mut self, photos: &[&'p Photo], size: usize) -> Vec<&'p Photo> {
+ if is_single_moment(photos, |photo| photo.creation_time) {
+ let mut shuffled = photos.to_vec();
+ self.rng.shuffle(&mut shuffled);
+ shuffled.truncate(size);
+ return shuffled;
+ }
+ let mut selected = Vec::with_capacity(size);
+ for mut bucket in time_buckets(photos, size, |photo| photo.creation_time) {
+ self.rng.shuffle(&mut bucket);
+ if let Some(photo) = bucket
+ .into_iter()
+ .find(|photo| !is_too_close(photo, &selected))
+ {
+ selected.push(photo);
+ }
+ }
+ for photo in photos {
+ if selected.len() >= size {
+ break;
+ }
+ if !selected.iter().any(|chosen| chosen.id == photo.id)
+ && !is_too_close(photo, &selected)
+ {
+ selected.push(photo);
+ }
+ }
+ selected
+ }
+}
+
+fn ranked<'p>(
+ photos: &[&'p Photo],
+ size: usize,
+ spread: Spread,
+ signals: &dyn PhotoSignals,
+) -> Vec<&'p Photo> {
+ let candidates: Vec<Candidate> = photos
+ .iter()
+ .map(|&photo| Candidate {
+ photo,
+ score: f64::from(signals.face_weight(photo.id)) * FACE_WEIGHT_SCORE
+ + signals.nostalgia(photo.id).map_or(0.0, f64::from),
+ })
+ .collect();
+ match spread {
+ Spread::None => ranked_flat(candidates, size, signals),
+ Spread::OverTime => ranked_over_time(candidates, size, signals),
+ Spread::AcrossYears => ranked_across_years(candidates, size, signals),
+ }
+}
+
+fn ranked_flat<'p>(
+ mut candidates: Vec<Candidate<'p>>,
+ size: usize,
+ signals: &dyn PhotoSignals,
+) -> Vec<&'p Photo> {
+ sort_by_score(&mut candidates);
+ let total = candidates.len();
+ let mut selected: Vec<&Photo> = Vec::with_capacity(size);
+ let mut skipped = 0;
+ for candidate in candidates {
+ if selected.len() >= size {
+ break;
+ }
+ let photo = candidate.photo;
+ if !selected.is_empty()
+ && (is_too_close(photo, &selected)
+ || (total - skipped > size && is_near_duplicate(photo, &selected, signals)))
+ {
+ skipped += 1;
+ continue;
+ }
+ selected.push(photo);
+ }
+ selected
+}
+
+fn ranked_over_time<'p>(
+ candidates: Vec<Candidate<'p>>,
+ size: usize,
+ signals: &dyn PhotoSignals,
+) -> Vec<&'p Photo> {
+ if is_single_moment(&candidates, |candidate| candidate.photo.creation_time) {
+ return ranked_flat(candidates, size, signals);
+ }
+ let mut selected: Vec<&Photo> = Vec::with_capacity(size);
+ for mut bucket in time_buckets(&candidates, size, |candidate| candidate.photo.creation_time) {
+ sort_by_score(&mut bucket);
+ let distinct: Vec<Candidate> = bucket
+ .iter()
+ .copied()
+ .filter(|candidate| !is_near_duplicate(candidate.photo, &selected, signals))
+ .collect();
+ let pool = if distinct.is_empty() {
+ bucket
+ } else {
+ distinct
+ };
+ if let Some(winner) = pool
+ .into_iter()
+ .find(|candidate| !is_too_close(candidate.photo, &selected))
+ {
+ selected.push(winner.photo);
+ }
+ }
+ if selected.len() < size {
+ let chosen: HashSet<i64> = selected.iter().map(|photo| photo.id).collect();
+ let mut rest: Vec<Candidate> = candidates
+ .into_iter()
+ .filter(|candidate| !chosen.contains(&candidate.photo.id))
+ .collect();
+ sort_by_score(&mut rest);
+ for candidate in rest {
+ if selected.len() >= size {
+ break;
+ }
+ if !is_near_duplicate(candidate.photo, &selected, signals)
+ && !is_too_close(candidate.photo, &selected)
+ {
+ selected.push(candidate.photo);
+ }
+ }
+ }
+ selected
+}
+
+fn ranked_across_years<'p>(
+ candidates: Vec<Candidate<'p>>,
+ size: usize,
+ signals: &dyn PhotoSignals,
+) -> Vec<&'p Photo> {
+ let total = candidates.len();
+ let mut years: BTreeMap<i32, Vec<Candidate>> = BTreeMap::new();
+ for candidate in candidates {
+ years
+ .entry(candidate.photo.date.year)
+ .or_default()
+ .push(candidate);
+ }
+ let years: Vec<Vec<&Photo>> = years
+ .into_values()
+ .rev()
+ .map(|mut year| {
+ sort_by_score(&mut year);
+ year.into_iter().map(|candidate| candidate.photo).collect()
+ })
+ .collect();
+ let mut skipped = 0;
+ round_robin(&years, size, |round, photo, selected| {
+ let rejected = is_too_close(photo, selected)
+ || (round > 0 && total - skipped > size && is_near_duplicate(photo, selected, signals));
+ if rejected {
+ skipped += 1;
+ }
+ !rejected
+ })
+}
+
+fn round_robin<'p>(
+ years: &[Vec<&'p Photo>],
+ size: usize,
+ mut accept: impl FnMut(usize, &Photo, &[&'p Photo]) -> bool,
+) -> Vec<&'p Photo> {
+ let rounds = years.iter().map(Vec::len).max().unwrap_or(0);
+ let mut selected = Vec::with_capacity(size);
+ for round in 0..rounds {
+ for photo in years.iter().filter_map(|year| year.get(round)) {
+ if selected.len() >= size {
+ return selected;
+ }
+ if accept(round, photo, &selected) {
+ selected.push(*photo);
+ }
+ }
+ }
+ selected
+}
+
+fn by_year<'p>(photos: &[&'p Photo]) -> BTreeMap<i32, Vec<&'p Photo>> {
+ let mut years: BTreeMap<i32, Vec<&Photo>> = BTreeMap::new();
+ for &photo in photos {
+ years.entry(photo.date.year).or_default().push(photo);
+ }
+ years
+}
+
+fn time_buckets<T: Copy>(items: &[T], count: usize, time: impl Fn(&T) -> i64) -> Vec<Vec<T>> {
+ let mut buckets = vec![Vec::new(); count];
+ let (Some(first), Some(last)) = (items.first(), items.last()) else {
+ return buckets;
+ };
+ let start = time(first);
+ let range = i128::from(time(last) - start) + 1;
+ for item in items {
+ let index = i128::from(time(item) - start) * count as i128 / range;
+ buckets[(index as usize).min(count - 1)].push(*item);
+ }
+ buckets
+}
+
+fn sort_by_score(candidates: &mut [Candidate]) {
+ candidates.sort_by(|a, b| {
+ b.score.total_cmp(&a.score).then_with(|| {
+ (a.photo.creation_time, a.photo.id).cmp(&(b.photo.creation_time, b.photo.id))
+ })
+ });
+}
+
+fn is_single_moment<T>(items: &[T], time: impl Fn(&T) -> i64) -> bool {
+ items.first().map(&time) == items.last().map(&time)
+}
+
+fn is_too_close(photo: &Photo, selected: &[&Photo]) -> bool {
+ selected
+ .iter()
+ .any(|other| (photo.creation_time - other.creation_time).abs() < MINIMUM_TIME_GAP)
+}
+
+fn is_near_duplicate(photo: &Photo, selected: &[&Photo], signals: &dyn PhotoSignals) -> bool {
+ selected.iter().any(|other| {
+ signals
+ .similarity(photo.id, other.id)
+ .is_some_and(|similarity| similarity > NEAR_DUPLICATE_SIMILARITY)
+ })
+}
+
+#[cfg(test)]
+mod tests {
+ use std::collections::{HashMap, HashSet};
+
+ use super::Selector;
+ use crate::memories::input::{MemoryFile, PhotoSignals};
+ use crate::memories::photo::{Photo, prepare};
+ use crate::memories::tests::{file, micros};
+
+ #[derive(Default)]
+ struct Signals {
+ face_weights: HashMap<i64, u32>,
+ nostalgia: HashMap<i64, f32>,
+ near_duplicates: HashSet<(i64, i64)>,
+ }
+
+ impl PhotoSignals for Signals {
+ fn face_weight(&self, file_id: i64) -> u32 {
+ self.face_weights.get(&file_id).copied().unwrap_or(0)
+ }
+
+ fn nostalgia(&self, file_id: i64) -> Option<f32> {
+ self.nostalgia.get(&file_id).copied()
+ }
+
+ fn similarity(&self, file_id: i64, other_file_id: i64) -> Option<f32> {
+ let pair = (file_id.min(other_file_id), file_id.max(other_file_id));
+ Some(if self.near_duplicates.contains(&pair) {
+ 0.95
+ } else {
+ 0.1
+ })
+ }
+ }
+
+ fn daily(first_id: i64, start: &str, count: i64) -> Vec<MemoryFile> {
+ let start = micros(start);
+ (0..count)
+ .map(|index| MemoryFile {
+ creation_time: start + index * 86_400_000_000,
+ ..file(first_id + index, "1970-01-01T00:00:00")
+ })
+ .collect()
+ }
+
+ fn ids(photos: &[&Photo]) -> Vec<i64> {
+ photos.iter().map(|photo| photo.id).collect()
+ }
+
+ #[test]
+ fn single_year_picks_rank_faces_then_nostalgia_and_skip_duplicates_and_bursts() {
+ let mut files = daily(1, "2024-01-01T12:00:00", 15);
+ files[12].creation_time = micros("2024-01-12T12:05:00");
+ let photos = prepare(&files);
+ let signals = Signals {
+ face_weights: HashMap::from([(3, 10)]),
+ nostalgia: (1..=15).map(|id| (id, id as f32 / 100.0)).collect(),
+ near_duplicates: HashSet::from([(14, 15)]),
+ };
+
+ let selected = Selector::new(Some(&signals), 0).best(photos.iter().collect(), None);
+
+ assert_eq!(ids(&selected), [3, 5, 6, 7, 8, 9, 10, 11, 13, 15]);
+ }
+
+ fn six_years_of_four_photos() -> Vec<MemoryFile> {
+ (2015..2021)
+ .flat_map(|year| daily(year * 10, &format!("{year}-06-01T12:00:00"), 4))
+ .collect()
+ }
+
+ fn assert_three_per_year(selected: &[&Photo]) {
+ assert_eq!(selected.len(), 18);
+ for year in 2015..2021 {
+ let from_year = selected
+ .iter()
+ .filter(|photo| photo.id / 10 == year)
+ .count();
+ assert_eq!(from_year, 3, "{year}");
+ }
+ }
+
+ #[test]
+ fn many_years_get_three_photos_each_in_turn() {
+ let photos = prepare(&six_years_of_four_photos());
+ let signals = Signals::default();
+
+ let selected = Selector::new(Some(&signals), 0).best(photos.iter().collect(), None);
+
+ assert_three_per_year(&selected);
+ }
+
+ #[test]
+ fn random_picks_take_three_per_year_even_when_a_size_is_preferred() {
+ let photos = prepare(&six_years_of_four_photos());
+ let signals = Signals::default();
+
+ let random = Selector::new(None, 0).best(photos.iter().collect(), Some(20));
+ let ranked = Selector::new(Some(&signals), 0).best(photos.iter().collect(), Some(20));
+
+ assert_three_per_year(&random);
+ assert_eq!(ranked.len(), 20);
+ }
+
+ #[test]
+ fn random_picks_spread_over_time_and_follow_the_seed() {
+ let photos = prepare(&daily(0, "2024-01-01T12:00:00", 40));
+ let pick =
+ |seed| ids(&Selector::new(None, seed).best_over_time(photos.iter().collect(), 10));
+
+ let selected = pick(5);
+
+ assert_eq!(selected.len(), 10);
+ for bucket in 0..10 {
+ assert_eq!(selected[bucket] / 4, bucket as i64, "{selected:?}");
+ }
+ assert_eq!(selected, pick(5));
+ assert_ne!(selected, pick(6));
+ }
+
+ #[test]
+ fn small_sets_are_kept_whole_in_chronological_order() {
+ let photos = prepare(&daily(0, "2024-01-01T12:00:00", 5));
+ let reversed: Vec<&Photo> = photos.iter().rev().collect();
+
+ let selected = Selector::new(None, 0).best(reversed, None);
+
+ assert_eq!(ids(&selected), [0, 1, 2, 3, 4]);
+ }
+}
diff --git a/rust/crates/photos/src/memories/time.rs b/rust/crates/photos/src/memories/time.rs
new file mode 100644
index 0000000000..c3b0d88d2a
--- /dev/null
+++ b/rust/crates/photos/src/memories/time.rs
@@ -0,0 +1,396 @@
+use std::cmp::Reverse;
+use std::collections::HashMap;
+
+use super::calendar::{LocalDate, MICROS_PER_DAY};
+use super::input::Period;
+use super::output::{Memory, MemoryKind, TimeMemory};
+use super::photo::Photo;
+use super::selector::Selector;
+use super::{MINIMUM_MEMORY_LENGTH, UPDATE_FREQUENCY_DAYS, unused_photos};
+
+const RECENT_SELECTION_SIZE: usize = 10;
+const MONTH_SELECTION_SIZE: usize = 20;
+const SINGLE_YEAR_MONTH_MEMORIES: usize = 2;
+const MINIMUM_YEARS_FOR_MONTH_THROUGH_THE_YEARS: usize = 4;
+const MINIMUM_SIGNIFICANT_YEARS_FOR_THROUGH_THE_YEARS: usize = 3;
+const SIGNIFICANT_DAY_SHARE: f64 = 0.25;
+const SIGNIFICANT_WEEK_SHARE: f64 = 0.40;
+const DAYS_PER_YEAR: i64 = 365;
+
+pub(super) fn memories(
+ available: &[&Photo],
+ all_photos: &[Photo],
+ period: Period,
+ selector: &mut Selector,
+) -> Vec<Memory> {
+ let mut memories = recent_memories(all_photos, period, selector);
+ let cutoff = period.now - DAYS_PER_YEAR * MICROS_PER_DAY;
+ let historical: Vec<&Photo> = available
+ .iter()
+ .copied()
+ .filter(|photo| photo.creation_time <= cutoff)
+ .collect();
+ let average_daily_photos = available.len() as f64 / DAYS_PER_YEAR as f64;
+
+ let mut past_memories = day_memories(
+ &historical,
+ period,
+ average_daily_photos * SIGNIFICANT_DAY_SHARE,
+ selector,
+ );
+ if past_memories.is_empty() {
+ past_memories = week_memories(
+ &historical,
+ period,
+ average_daily_photos * SIGNIFICANT_WEEK_SHARE,
+ selector,
+ );
+ }
+ let month_photos = unused_photos(historical, &past_memories);
+ past_memories.extend(month_memories(&month_photos, period, selector));
+ memories.extend(past_memories);
+ memories
+}
+
+fn recent_memories(photos: &[Photo], period: Period, selector: &mut Selector) -> Vec<Memory> {
+ let today = period.today();
+ let week_start = today.plus_days(1 - today.weekday());
+ let month_start = LocalDate::new(today.year, today.month, 1);
+ [
+ (
+ TimeMemory::LastWeek,
+ week_start.plus_days(-7),
+ week_start,
+ week_start.plus_days(7),
+ ),
+ (
+ TimeMemory::LastMonth,
+ LocalDate::new(today.year, today.month - 1, 1),
+ month_start,
+ LocalDate::new(today.year, today.month + 1, 1),
+ ),
+ ]
+ .into_iter()
+ .filter_map(|(kind, source_start, show_start, show_end)| {
+ let candidates: Vec<&Photo> = photos
+ .iter()
+ .filter(|photo| (source_start..show_start).contains(&photo.date))
+ .collect();
+ (candidates.len() >= MINIMUM_MEMORY_LENGTH).then(|| {
+ Memory::new(
+ MemoryKind::Time(kind),
+ &selector.best_over_time(candidates, RECENT_SELECTION_SIZE),
+ period.start_of(show_start),
+ period.start_of(show_end),
+ )
+ })
+ })
+ .collect()
+}
+
+fn day_memories(
+ photos: &[&Photo],
+ period: Period,
+ significance_threshold: f64,
+ selector: &mut Selector,
+) -> Vec<Memory> {
+ let show_dates = show_dates(period.today());
+ let mut groups: HashMap<(i32, i32), HashMap<i32, Vec<&Photo>>> = HashMap::new();
+ for &photo in photos {
+ let month_day = (photo.date.month, photo.date.day);
+ if show_dates
+ .get(&month_day)
+ .is_some_and(|show_date| photo.date.year < show_date.year)
+ {
+ groups
+ .entry(month_day)
+ .or_default()
+ .entry(photo.date.year)
+ .or_default()
+ .push(photo);
+ }
+ }
+ let mut month_days: Vec<(LocalDate, (i32, i32))> = groups
+ .keys()
+ .map(|month_day| (show_dates[month_day], *month_day))
+ .collect();
+ month_days.sort();
+
+ let mut memories = Vec::new();
+ for (show_date, (month, day)) in month_days {
+ let years = &groups[&(month, day)];
+ let significant_years = significant_years(years, significance_threshold);
+ let first_date_to_show = period.start_of(show_date.plus_days(-1));
+ let last_date_to_show = period.start_of(show_date.plus_days(1));
+ if significant_years.len() >= MINIMUM_SIGNIFICANT_YEARS_FOR_THROUGH_THE_YEARS {
+ let kind = TimeMemory::Day {
+ date: LocalDate::new(significant_years[0], month, day),
+ years_ago: None,
+ };
+ let photos = years.values().flatten().copied().collect();
+ memories.push(Memory::new(
+ MemoryKind::Time(kind),
+ &selector.best(photos, None),
+ first_date_to_show,
+ last_date_to_show,
+ ));
+ } else {
+ for year in significant_years {
+ let kind = TimeMemory::Day {
+ date: LocalDate::new(year, month, day),
+ years_ago: Some(show_date.year - year),
+ };
+ memories.push(Memory::new(
+ MemoryKind::Time(kind),
+ &selector.best(years[&year].clone(), None),
+ first_date_to_show,
+ last_date_to_show,
+ ));
+ }
+ }
+ }
+ memories
+}
+
+fn week_memories(
+ photos: &[&Photo],
+ period: Period,
+ significance_threshold: f64,
+ selector: &mut Selector,
+) -> Vec<Memory> {
+ let today = period.today();
+ let mut years: HashMap<i32, Vec<&Photo>> = HashMap::new();
+ for &photo in photos {
+ if photo.date.week_of_year() == today.week_of_year() && photo.date.year < today.year {
+ years.entry(photo.date.year).or_default().push(photo);
+ }
+ }
+ let significant_years = significant_years(&years, significance_threshold);
+ let first_date_to_show = period.now - MICROS_PER_DAY;
+ let last_date_to_show = period.now + UPDATE_FREQUENCY_DAYS * MICROS_PER_DAY;
+ if significant_years.len() >= MINIMUM_SIGNIFICANT_YEARS_FOR_THROUGH_THE_YEARS {
+ let photos = years.values().flatten().copied().collect();
+ return vec![Memory::new(
+ MemoryKind::Time(TimeMemory::Week { years_ago: None }),
+ &selector.best(photos, None),
+ first_date_to_show,
+ last_date_to_show,
+ )];
+ }
+ significant_years
+ .into_iter()
+ .map(|year| {
+ let kind = TimeMemory::Week {
+ years_ago: Some(today.year - year),
+ };
+ Memory::new(
+ MemoryKind::Time(kind),
+ &selector.best(years[&year].clone(), None),
+ first_date_to_show,
+ last_date_to_show,
+ )
+ })
+ .collect()
+}
+
+fn month_memories(photos: &[&Photo], period: Period, selector: &mut Selector) -> Vec<Memory> {
+ let today = period.today();
+ let mut years: HashMap<i32, Vec<&Photo>> = HashMap::new();
+ for &photo in photos {
+ if photo.date.month == today.month && photo.date.year < today.year {
+ years.entry(photo.date.year).or_default().push(photo);
+ }
+ }
+ let mut years: Vec<(i32, Vec<&Photo>)> = years.into_iter().collect();
+ years.sort_by_key(|(year, photos)| (Reverse(photos.len()), Reverse(*year)));
+
+ let first_date_to_show = period.now;
+ let last_date_to_show = period.start_of(LocalDate::new(today.year, today.month + 1, 1));
+ let mut years = years.into_iter();
+ let mut memories: Vec<Memory> = years
+ .by_ref()
+ .take(SINGLE_YEAR_MONTH_MEMORIES)
+ .map(|(year, photos)| {
+ let kind = TimeMemory::Month {
+ year,
+ month: today.month,
+ years_ago: Some(today.year - year),
+ };
+ Memory::new(
+ MemoryKind::Time(kind),
+ &selector.best(photos, Some(MONTH_SELECTION_SIZE)),
+ first_date_to_show,
+ last_date_to_show,
+ )
+ })
+ .collect();
+ let remaining_years: Vec<(i32, Vec<&Photo>)> = years.collect();
+ if remaining_years.len() >= MINIMUM_YEARS_FOR_MONTH_THROUGH_THE_YEARS {
+ let kind = TimeMemory::Month {
+ year: today.year,
+ month: today.month,
+ years_ago: None,
+ };
+ let photos = remaining_years
+ .into_iter()
+ .flat_map(|(_, photos)| photos)
+ .collect();
+ memories.push(Memory::new(
+ MemoryKind::Time(kind),
+ &selector.best(photos, Some(MONTH_SELECTION_SIZE)),
+ first_date_to_show,
+ last_date_to_show,
+ ));
+ }
+ memories
+}
+
+fn show_dates(today: LocalDate) -> HashMap<(i32, i32), LocalDate> {
+ let mut dates = HashMap::new();
+ for offset in 0..=UPDATE_FREQUENCY_DAYS {
+ let date = today.plus_days(offset);
+ dates.insert((date.month, date.day), date);
+ if (date.month, date.day) == (2, 28) && !date.is_in_leap_year() {
+ dates.insert((2, 29), date);
+ }
+ }
+ dates
+}
+
+fn significant_years(years: &HashMap<i32, Vec<&Photo>>, threshold: f64) -> Vec<i32> {
+ let mut significant: Vec<i32> = years
+ .iter()
+ .filter(|(_, photos)| photos.len() as f64 > threshold)
+ .map(|(year, _)| *year)
+ .collect();
+ significant.sort_by_key(|year| Reverse(*year));
+ significant
+}
+
+#[cfg(test)]
+mod tests {
+ use super::memories;
+ use crate::memories::calendar::LocalDate;
+ use crate::memories::input::MemoryFile;
+ use crate::memories::output::{Memory, MemoryKind, TimeMemory};
+ use crate::memories::photo::prepare;
+ use crate::memories::selector::Selector;
+ use crate::memories::tests::{files_on, micros, period};
+
+ fn time_memories(files: &[MemoryFile], now: &str) -> Vec<Memory> {
+ let photos = prepare(files);
+ let available: Vec<_> = photos.iter().collect();
+ memories(
+ &available,
+ &photos,
+ period(now),
+ &mut Selector::new(None, 0),
+ )
+ }
+
+ fn day(year: i32, month: i32, day: i32, years_ago: Option<i32>) -> MemoryKind {
+ MemoryKind::Time(TimeMemory::Day {
+ date: LocalDate { year, month, day },
+ years_ago,
+ })
+ }
+
+ #[test]
+ fn upcoming_days_go_through_the_years_from_three_significant_years() {
+ let mut files = Vec::new();
+ for year in 2020..2023 {
+ files.extend(files_on(i64::from(year) * 10, &format!("{year}-10-30"), 2));
+ }
+ files.extend(files_on(1, "2019-11-01", 2));
+
+ let memories = time_memories(&files, "2026-10-29T09:00:00");
+
+ let kinds: Vec<MemoryKind> = memories.iter().map(|memory| memory.kind).collect();
+ assert_eq!(kinds, [day(2022, 10, 30, None), day(2019, 11, 1, Some(7))]);
+ assert_eq!(memories[0].file_ids.len(), 6);
+ assert_eq!(
+ memories[0].first_date_to_show,
+ micros("2026-10-29T00:00:00")
+ );
+ assert_eq!(memories[0].last_date_to_show, micros("2026-10-31T00:00:00"));
+ assert_eq!(
+ memories[1].first_date_to_show,
+ micros("2026-10-31T00:00:00")
+ );
+ }
+
+ #[test]
+ fn leap_days_show_on_february_twenty_eighth_in_common_years() {
+ let memories = time_memories(&files_on(1, "2024-02-29", 2), "2027-02-27T09:00:00");
+
+ assert_eq!(memories[0].kind, day(2024, 2, 29, Some(3)));
+ assert_eq!(
+ memories[0].first_date_to_show,
+ micros("2027-02-27T00:00:00")
+ );
+ assert_eq!(memories[0].last_date_to_show, micros("2027-03-01T00:00:00"));
+ }
+
+ #[test]
+ fn months_show_the_two_busiest_years_then_the_rest_through_the_years() {
+ let mut files = files_on(150, "2015-10-20", 5);
+ files.extend(files_on(160, "2016-10-20", 4));
+ for year in 2017..2021 {
+ files.extend(files_on(i64::from(year) * 10, &format!("{year}-10-20"), 1));
+ }
+ files.extend(files_on(1, "2015-10-06", 1));
+
+ let memories = time_memories(&files, "2026-10-05T09:00:00");
+
+ let month = |year, years_ago| {
+ MemoryKind::Time(TimeMemory::Month {
+ year,
+ month: 10,
+ years_ago,
+ })
+ };
+ let kinds: Vec<MemoryKind> = memories.iter().map(|memory| memory.kind).collect();
+ assert_eq!(
+ kinds,
+ [
+ day(2015, 10, 6, Some(11)),
+ month(2015, Some(11)),
+ month(2016, Some(10)),
+ month(2026, None),
+ ]
+ );
+ assert_eq!(memories[1].file_ids, [150, 151, 152, 153, 154]);
+ assert_eq!(memories[3].file_ids, [20170, 20180, 20190, 20200]);
+ assert_eq!(
+ memories[3].first_date_to_show,
+ micros("2026-10-05T09:00:00")
+ );
+ assert_eq!(memories[3].last_date_to_show, micros("2026-11-01T00:00:00"));
+ }
+
+ #[test]
+ fn photos_dated_in_the_show_year_are_not_past_memories() {
+ let mut files = files_on(1, "2015-10-30", 2);
+ for file in &mut files {
+ file.local_date_time = Some("2026-10-30T10:00:00".to_owned());
+ }
+
+ assert!(time_memories(&files, "2026-10-29T09:00:00").is_empty());
+ }
+
+ #[test]
+ fn recent_weeks_and_months_need_five_photos() {
+ let mut files = files_on(1, "2026-10-21", 5);
+ files.extend(files_on(10, "2026-09-15", 4));
+
+ let memories = time_memories(&files, "2026-10-29T09:00:00");
+
+ assert_eq!(memories.len(), 1);
+ assert_eq!(memories[0].kind, MemoryKind::Time(TimeMemory::LastWeek));
+ assert_eq!(
+ memories[0].first_date_to_show,
+ micros("2026-10-26T00:00:00")
+ );
+ assert_eq!(memories[0].last_date_to_show, micros("2026-11-02T00:00:00"));
+ }
+}