geopic-tag-reader 1.1.5__py3-none-any.whl → 1.3.0__py3-none-any.whl

geopic_tag_reader/__init__.py

@@ -2,4 +2,4 @@
 GeoPicTagReader
 """
 
-__version__ = "1.1.5"
+__version__ = "1.3.0"

geopic_tag_reader/main.py

@@ -25,7 +25,10 @@ def read(
         _ = i18n_init(lang)
         print(_("Latitude:"), metadata.lat)
         print(_("Longitude:"), metadata.lon)
-        print(_("Timestamp:"), metadata.ts.isoformat())
+        print(_("Timestamp:"), metadata.ts)
+        if metadata.ts_by_source is not None:
+            print("  -", (metadata.ts_by_source.gps or _("not set")), _("(GPS)"))
+            print("  -", (metadata.ts_by_source.camera or _("not set")), _("(Camera)"))
         print(_("Heading:"), metadata.heading)
         print(_("Type:"), metadata.type)
         print(_("Make:"), metadata.make)
@@ -34,6 +37,7 @@ def read(
         print(_("Crop parameters:"), metadata.crop)
         print(_("Pitch:"), metadata.pitch)
         print(_("Roll:"), metadata.roll)
+        print(_("Yaw:"), metadata.yaw)
 
         if len(metadata.tagreader_warnings) > 0:
             print(_("Warnings raised by reader:"))

geopic_tag_reader/reader.py

@@ -39,6 +39,32 @@ class CropValues:
     top: int
 
 
+@dataclass
+class TimeBySource:
+    """All datetimes read from available sources
+
+    Attributes:
+        gps (datetime): Time read from GPS clock
+        camera (datetime): Time read from camera clock (DateTimeOriginal)
+    """
+
+    gps: Optional[datetime.datetime] = None
+    camera: Optional[datetime.datetime] = None
+
+    def getBest(self) -> Optional[datetime.datetime]:
+        """Get the best available datetime to use"""
+        if self.gps is not None and self.camera is None:
+            return self.gps
+        elif self.gps is None and self.camera is not None:
+            return self.camera
+        elif self.gps is None and self.camera is None:
+            return None
+        elif self.camera.microsecond > 0 and self.gps.microsecond == 0:  # type: ignore
+            return self.camera
+        else:
+            return self.gps
+
+
 @dataclass
 class GeoPicTags:
     """Tags associated to a geolocated picture
@@ -47,7 +73,7 @@ class GeoPicTags:
         lat (float): GPS Latitude (in WGS84)
         lon (float): GPS Longitude (in WGS84)
         ts (datetime): The capture date (date & time with timezone)
-        heading (int): Picture heading/yaw (in degrees, North = 0°, East = 90°, South = 180°, West = 270°)
+        heading (int): Picture GPS heading (in degrees, North = 0°, East = 90°, South = 180°, West = 270°). Value is computed based on image center (if yaw=0°)
         type (str): The kind of picture (flat, equirectangular)
         make (str): The camera manufacturer name
         model (str): The camera model name
@@ -58,6 +84,8 @@ class GeoPicTags:
         altitude (float): altitude (in m) (optional)
         pitch (float): Picture pitch angle, compared to horizon (in degrees, bottom = -90°, horizon = 0°, top = 90°)
         roll (float): Picture roll angle, on a right/left axis (in degrees, left-arm down = -90°, flat = 0°, right-arm down = 90°)
+        yaw (float): Picture yaw angle, on a vertical axis (in degrees, front = 0°, right = 90°, rear = 180°, left = 270°). This offsets the center image from GPS direction for a correct 360° sphere correction
+        ts_by_source (TimeBySource): all read timestamps from image, for finer processing.
 
 
     Implementation note: this needs to be sync with the PartialGeoPicTags structure
@@ -77,6 +105,8 @@ class GeoPicTags:
     altitude: Optional[float] = None
     pitch: Optional[float] = None
     roll: Optional[float] = None
+    yaw: Optional[float] = None
+    ts_by_source: Optional[TimeBySource] = None
 
 
 class InvalidExifException(Exception):
@@ -111,6 +141,8 @@ class PartialGeoPicTags:
     altitude: Optional[float] = None
     pitch: Optional[float] = None
     roll: Optional[float] = None
+    yaw: Optional[float] = None
+    ts_by_source: Optional[TimeBySource] = None
 
 
 class PartialExifException(Exception):
@@ -184,35 +216,21 @@ def readPictureMetadata(picture: bytes, lang_code: str = "en") -> GeoPicTags:
     if lon is not None and (lon < -180 or lon > 180):
         raise InvalidExifException(_("Read longitude is out of WGS84 bounds (should be in [-180, 180])"))
 
-    # Parse date/time
-    d, llw = decodeGPSDateTime(data, "Exif.GPSInfo", _, lat, lon)
+    # Parse GPS date/time
+    gpsTs, llw = decodeGPSDateTime(data, "Exif.GPSInfo", _, lat, lon)
 
     if len(llw) > 0:
         warnings.extend(llw)
 
-    if d is None:
-        d, llw = decodeGPSDateTime(data, "Xmp.exif", _, lat, lon)
+    if gpsTs is None:
+        gpsTs, llw = decodeGPSDateTime(data, "Xmp.exif", _, lat, lon)
         if len(llw) > 0:
             warnings.extend(llw)
 
-    for exifField in [
-        "Exif.Image.DateTimeOriginal",
-        "Exif.Photo.DateTimeOriginal",
-        "Exif.Image.DateTime",
-        "Xmp.GPano.SourceImageCreateTime",
-    ]:
-        if d is None:
-            d, llw = decodeDateTimeOriginal(data, exifField, _, lat, lon)
-            if len(llw) > 0:
-                warnings.extend(llw)
-
-        if d is not None:
-            break
-
-    if d is None and isExifTagUsable(data, "MAPGpsTime"):
+    if gpsTs is None and isExifTagUsable(data, "MAPGpsTime"):
         try:
             year, month, day, hour, minutes, seconds, milliseconds = [int(dp) for dp in data["MAPGpsTime"].split("_")]
-            d = datetime.datetime(
+            gpsTs = datetime.datetime(
                 year,
                 month,
                 day,
@@ -226,57 +244,59 @@ def readPictureMetadata(picture: bytes, lang_code: str = "en") -> GeoPicTags:
         except Exception as e:
             warnings.append(_("Skipping Mapillary date/time as it was not recognized: {v}").format(v=data["MAPGpsTime"]))
 
-    # Heading/Yaw
-    heading = None
-    if isExifTagUsable(data, "Xmp.GPano.PoseHeadingDegrees", float) and isExifTagUsable(data, "Exif.GPSInfo.GPSImgDirection", Fraction):
-        gpsDir = int(round(float(Fraction(data["Exif.GPSInfo.GPSImgDirection"]))))
-        gpanoHeading = int(round(float(data["Xmp.GPano.PoseHeadingDegrees"])))
-        if gpsDir > 0 and gpanoHeading == 0:
-            heading = gpsDir
-        elif gpsDir == 0 and gpanoHeading > 0:
-            heading = gpanoHeading
-        else:
-            if gpsDir != gpanoHeading:
-                warnings.append(_("Contradicting heading values found, GPSImgDirection value is used"))
-            heading = gpsDir
+    # Parse camera date/time
+    cameraTs = None
+    for exifGroup, dtField, subsecField in [
+        ("Exif.Photo", "DateTimeOriginal", "SubSecTimeOriginal"),
+        ("Exif.Image", "DateTimeOriginal", "SubSecTimeOriginal"),
+        ("Exif.Image", "DateTime", "SubSecTimeOriginal"),
+        ("Xmp.GPano", "SourceImageCreateTime", "SubSecTimeOriginal"),
+        ("Xmp.exif", "DateTimeOriginal", "SubsecTimeOriginal"),  # Case matters
+    ]:
+        if cameraTs is None:
+            cameraTs, llw = decodeDateTimeOriginal(data, exifGroup, dtField, subsecField, _, lat, lon)
+            if len(llw) > 0:
+                warnings.extend(llw)
 
-    elif isExifTagUsable(data, "Xmp.GPano.PoseHeadingDegrees", float):
-        heading = int(round(float(data["Xmp.GPano.PoseHeadingDegrees"])))
+        if cameraTs is not None:
+            break
+    tsSources = TimeBySource(gps=gpsTs, camera=cameraTs) if gpsTs or cameraTs else None
+    d = tsSources.getBest() if tsSources is not None else None
 
-    elif isExifTagUsable(data, "Exif.GPSInfo.GPSImgDirection", Fraction):
+    # GPS Heading
+    heading = None
+    if isExifTagUsable(data, "Exif.GPSInfo.GPSImgDirection", Fraction):
         heading = int(round(float(Fraction(data["Exif.GPSInfo.GPSImgDirection"]))))
 
     elif "MAPCompassHeading" in data and isExifTagUsable(data["MAPCompassHeading"], "TrueHeading", float):
         heading = int(round(float(data["MAPCompassHeading"]["TrueHeading"])))
 
-    # Pitch & roll
+    # Yaw / Pitch / roll
+    yaw = None
     pitch = None
     roll = None
-    exifPRFields = ["Xmp.Camera.$$", "Exif.GPSInfo.GPS$$", "Xmp.GPano.Pose$$Degrees", "Xmp.GPano.InitialView$$Degrees"]
-    # For each potential EXIF field
-    for exifField in exifPRFields:
-        # Try out both Pitch & Roll variants
-        for checkField in ["Pitch", "Roll"]:
-            exifCheckField = exifField.replace("$$", checkField)
+    exifYPRFields = {
+        "yaw": ["Xmp.Camera.Yaw", "Xmp.GPano.PoseHeadingDegrees"],
+        "pitch": ["Xmp.Camera.Pitch", "Xmp.GPano.PosePitchDegrees"],
+        "roll": ["Xmp.Camera.Roll", "Xmp.GPano.PoseRollDegrees"],
+    }
+    for ypr in exifYPRFields:
+        for exifTag in exifYPRFields[ypr]:
             foundValue = None
             # Look for float or fraction
-            if isExifTagUsable(data, exifCheckField, float):
-                foundValue = float(data[exifCheckField])
-            elif isExifTagUsable(data, exifCheckField, Fraction):
-                foundValue = float(Fraction(data[exifCheckField]))
+            if isExifTagUsable(data, exifTag, float):
+                foundValue = float(data[exifTag])
+            elif isExifTagUsable(data, exifTag, Fraction):
+                foundValue = float(Fraction(data[exifTag]))
 
-            # Save to correct variable (if not already set)
+            # Save found value
             if foundValue is not None:
-                if checkField == "Pitch":
-                    if pitch is None:
-                        pitch = foundValue
-                    else:
-                        continue
-                elif checkField == "Roll":
-                    if roll is None:
-                        roll = foundValue
-                    else:
-                        continue
+                if ypr == "yaw" and yaw is None:
+                    yaw = foundValue
+                elif ypr == "pitch" and pitch is None:
+                    pitch = foundValue
+                elif ypr == "roll" and roll is None:
+                    roll = foundValue
 
     # Make and model
     make = data.get("Exif.Image.Make") or data.get("MAPDeviceMake")
@@ -383,6 +403,8 @@ def readPictureMetadata(picture: bytes, lang_code: str = "en") -> GeoPicTags:
                 altitude=altitude,
                 pitch=pitch,
                 roll=roll,
+                yaw=yaw,
+                ts_by_source=tsSources,
             ),
         )
 
@@ -402,6 +424,8 @@ def readPictureMetadata(picture: bytes, lang_code: str = "en") -> GeoPicTags:
         altitude=altitude,
         pitch=pitch,
         roll=roll,
+        yaw=yaw,
+        ts_by_source=tsSources,
     )
 
 
@@ -492,20 +516,28 @@ def decodeLatLon(data: dict, group: str, _: Callable[[str], str]) -> Tuple[Optio
 
 
 def decodeDateTimeOriginal(
-    data: dict, datetimeField: str, _: Callable[[str], str], lat: Optional[float] = None, lon: Optional[float] = None
+    data: dict,
+    exifGroup: str,
+    datetimeField: str,
+    subsecField: str,
+    _: Callable[[str], str],
+    lat: Optional[float] = None,
+    lon: Optional[float] = None,
 ) -> Tuple[Optional[datetime.datetime], List[str]]:
     d = None
     warnings = []
+    dtField = f"{exifGroup}.{datetimeField}"
+    ssField = f"{exifGroup}.{subsecField}"
 
-    if d is None and isExifTagUsable(data, datetimeField):
+    if d is None and isExifTagUsable(data, dtField):
         try:
-            dateRaw = data[datetimeField][:10].replace(":", "-")
-            timeRaw = data[datetimeField][11:].split(":")
+            dateRaw = data[dtField][:10].replace(":", "-")
+            timeRaw = data[dtField][11:].split(":")
             hourRaw = int(timeRaw[0])
             minutesRaw = int(timeRaw[1])
             secondsRaw, microsecondsRaw, msw = decodeSecondsAndMicroSeconds(
-                timeRaw[2],
-                data["Exif.Photo.SubSecTimeOriginal"] if isExifTagUsable(data, "Exif.Photo.SubSecTimeOriginal", float) else "0",
+                timeRaw[2] if len(timeRaw) >= 3 else "0",
+                data[ssField] if isExifTagUsable(data, ssField, float) else "0",
                 _,
             )
             warnings += msw
@@ -522,7 +554,7 @@ def decodeDateTimeOriginal(
 
             # Timezone handling
             # Try to read from EXIF
-            tz = decodeTimeOffset(data, f"Exif.Photo.OffsetTime{'Original' if 'DateTimeOriginal' in datetimeField else ''}")
+            tz = decodeTimeOffset(data, f"{exifGroup}.OffsetTime{'Original' if 'DateTimeOriginal' in dtField else ''}")
             if tz is not None:
                 d = d.replace(tzinfo=tz)
 
@@ -543,9 +575,7 @@ def decodeDateTimeOriginal(
 
         except ValueError as e:
             warnings.append(
-                _("Skipping original date/time (from {datefield}) as it was not recognized: {v}").format(
-                    datefield=datetimeField, v=data[datetimeField]
-                )
+                _("Skipping original date/time (from {datefield}) as it was not recognized: {v}").format(datefield=dtField, v=data[dtField])
             )
 
     return (d, warnings)
@@ -583,7 +613,7 @@ def decodeGPSDateTime(
             if timeRaw:
                 seconds, microseconds, msw = decodeSecondsAndMicroSeconds(
                     str(float(timeRaw[2])),
-                    data["Exif.Photo.SubSecTimeOriginal"] if isExifTagUsable(data, "Exif.Photo.SubSecTimeOriginal", float) else "0",
+                    "0",  # No SubSecTimeOriginal, it's only for DateTimeOriginal
                     _,
                 )
 

geopic_tag_reader/sequence.py

@@ -0,0 +1,342 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional, List, Tuple
+from pathlib import PurePath
+from geopic_tag_reader.reader import GeoPicTags
+import datetime
+import math
+
+
+class SortMethod(str, Enum):
+    filename_asc = "filename-asc"
+    filename_desc = "filename-desc"
+    time_asc = "time-asc"
+    time_desc = "time-desc"
+
+
+@dataclass
+class MergeParams:
+    maxDistance: Optional[float] = None
+    maxRotationAngle: Optional[int] = None
+
+    def is_merge_needed(self):
+        # Only check max distance, as max rotation angle is only useful when dist is defined
+        return self.maxDistance is not None
+
+
+@dataclass
+class SplitParams:
+    maxDistance: Optional[int] = None
+    maxTime: Optional[int] = None
+
+    def is_split_needed(self):
+        return self.maxDistance is not None or self.maxTime is not None
+
+
+@dataclass
+class Picture:
+    filename: str
+    metadata: GeoPicTags
+
+    def distance_to(self, other) -> float:
+        """Computes distance in meters based on Haversine formula"""
+        R = 6371000
+        phi1 = math.radians(self.metadata.lat)
+        phi2 = math.radians(other.metadata.lat)
+        delta_phi = math.radians(other.metadata.lat - self.metadata.lat)
+        delta_lambda = math.radians(other.metadata.lon - self.metadata.lon)
+        a = math.sin(delta_phi / 2.0) ** 2 + math.cos(phi1) * math.cos(phi2) * math.sin(delta_lambda / 2.0) ** 2
+        c = 2 * math.atan2(math.sqrt(a), math.sqrt(1 - a))
+        distance = R * c
+        return distance
+
+
+class SplitReason(str, Enum):
+    time = "time"
+    distance = "distance"
+
+
+@dataclass
+class Split:
+    prevPic: Picture
+    nextPic: Picture
+    reason: SplitReason
+
+
+@dataclass
+class Sequence:
+    pictures: List[Picture]
+
+    def from_ts(self) -> Optional[datetime.datetime]:
+        """Start date/time of this sequence"""
+
+        if len(self.pictures) == 0:
+            return None
+        return self.pictures[0].metadata.ts
+
+    def to_ts(self) -> Optional[datetime.datetime]:
+        """End date/time of this sequence"""
+
+        if len(self.pictures) == 0:
+            return None
+        return self.pictures[-1].metadata.ts
+
+    def delta_with(self, otherSeq) -> Optional[Tuple[datetime.timedelta, float]]:
+        """
+        Delta between the end of this sequence and the start of the other one.
+        Returns a tuple (timedelta, distance in meters)
+        """
+
+        if len(self.pictures) == 0 or len(otherSeq.pictures) == 0:
+            return None
+
+        return (otherSeq.from_ts() - self.to_ts(), otherSeq.pictures[0].distance_to(self.pictures[-1]))  # type: ignore
+
+
+@dataclass
+class DispatchReport:
+    sequences: List[Sequence]
+    duplicate_pictures: Optional[List[Picture]] = None
+    sequences_splits: Optional[List[Split]] = None
+
+
+def sort_pictures(pictures: List[Picture], method: Optional[SortMethod] = SortMethod.time_asc) -> List[Picture]:
+    """Sorts pictures according to given strategy
+
+    Parameters
+    ----------
+    pictures : Picture[]
+        List of pictures to sort
+    method : SortMethod
+        Sort logic to adopt (time-asc, time-desc, filename-asc, filename-desc)
+
+    Returns
+    -------
+    Picture[]
+        List of pictures, sorted
+    """
+
+    if method is None:
+        method = SortMethod.time_asc
+
+    if method not in [item.value for item in SortMethod]:
+        raise Exception("Invalid sort strategy: " + str(method))
+
+    # Get the sort logic
+    strat, order = method.split("-")
+
+    # Sort based on filename
+    if strat == "filename":
+        # Check if pictures can be sorted by numeric notation
+        hasNonNumber = False
+        for p in pictures:
+            try:
+                int(PurePath(p.filename or "").stem)
+            except:
+                hasNonNumber = True
+                break
+
+        def sort_fct(p):
+            return PurePath(p.filename or "").stem if hasNonNumber else int(PurePath(p.filename or "").stem)
+
+        pictures.sort(key=sort_fct)
+
+    # Sort based on picture ts
+    elif strat == "time":
+        # Check if all pictures have GPS ts set
+        missingGpsTs = next(
+            (p for p in pictures if p.metadata is None or p.metadata.ts_by_source is None or p.metadata.ts_by_source.gps is None), None
+        )
+        if missingGpsTs:
+            # Check if all pictures have camera ts set
+            missingCamTs = next(
+                (p for p in pictures if p.metadata is None or p.metadata.ts_by_source is None or p.metadata.ts_by_source.camera is None),
+                None,
+            )
+            # Sort by best ts available
+            if missingCamTs:
+                pictures.sort(key=lambda p: p.metadata.ts.isoformat() if p.metadata is not None else "0000-00-00T00:00:00Z")
+            # Sort by camera ts
+            else:
+                pictures.sort(
+                    key=lambda p: (
+                        p.metadata.ts_by_source.camera.isoformat(),  # type: ignore
+                        p.metadata.ts_by_source.gps.isoformat() if p.metadata.ts_by_source.gps else "0000-00-00T00:00:00Z",  # type: ignore
+                    )
+                )
+        # Sort by GPS ts
+        else:
+            pictures.sort(
+                key=lambda p: (
+                    p.metadata.ts_by_source.gps.isoformat(),  # type: ignore
+                    p.metadata.ts_by_source.camera.isoformat() if p.metadata.ts_by_source.camera else "0000-00-00T00:00:00Z",  # type: ignore
+                )
+            )
+
+    if order == "desc":
+        pictures.reverse()
+
+    return pictures
+
+
+def find_duplicates(pictures: List[Picture], params: Optional[MergeParams] = None) -> Tuple[List[Picture], List[Picture]]:
+    """
+    Finds too similar pictures.
+    Note that input list should be properly sorted.
+
+    Parameters
+    ----------
+    pictures : list of sorted pictures to check
+    params : parameters used to consider two pictures as a duplicate
+
+    Returns
+    -------
+    (Non-duplicates pictures, Duplicates pictures)
+    """
+
+    if params is None or not params.is_merge_needed():
+        return (pictures, [])
+
+    nonDups: List[Picture] = []
+    dups: List[Picture] = []
+    lastNonDuplicatedPicId = 0
+
+    for i, currentPic in enumerate(pictures):
+        if i == 0:
+            nonDups.append(currentPic)
+            continue
+
+        prevPic = pictures[lastNonDuplicatedPicId]
+
+        if prevPic.metadata is None or currentPic.metadata is None:
+            nonDups.append(currentPic)
+            continue
+
+        # Compare distance
+        dist = prevPic.distance_to(currentPic)
+
+        if dist <= params.maxDistance:  # type: ignore
+            # Compare angle (if available on both images)
+            if params.maxRotationAngle is not None and prevPic.metadata.heading is not None and currentPic.metadata.heading is not None:
+                deltaAngle = abs(currentPic.metadata.heading - prevPic.metadata.heading)
+
+                if deltaAngle <= params.maxRotationAngle:
+                    dups.append(currentPic)
+                else:
+                    lastNonDuplicatedPicId = i
+                    nonDups.append(currentPic)
+            else:
+                dups.append(currentPic)
+        else:
+            lastNonDuplicatedPicId = i
+            nonDups.append(currentPic)
+
+    return (nonDups, dups)
+
+
+def split_in_sequences(pictures: List[Picture], splitParams: Optional[SplitParams] = SplitParams()) -> Tuple[List[Sequence], List[Split]]:
+    """
+    Split a list of pictures into many sequences.
+    Note that this function expect pictures to be sorted and have their metadata set.
+
+    Parameters
+    ----------
+    pictures : Picture[]
+            List of pictures to check, sorted and with metadata defined
+    splitParams : SplitParams
+            The parameters to define deltas between two pictures
+
+    Returns
+    -------
+    List[Sequence]
+            List of pictures splitted into smaller sequences
+    """
+
+    # No split parameters given -> just return given pictures
+    if splitParams is None or not splitParams.is_split_needed():
+        return ([Sequence(pictures)], [])
+
+    sequences: List[Sequence] = []
+    splits: List[Split] = []
+    currentPicList: List[Picture] = []
+
+    for pic in pictures:
+        if len(currentPicList) == 0:  # No checks for 1st pic
+            currentPicList.append(pic)
+        else:
+            lastPic = currentPicList[-1]
+
+            # Missing metadata -> skip
+            if lastPic.metadata is None or pic.metadata is None:
+                currentPicList.append(pic)
+                continue
+
+            # Time delta
+            timeDelta = lastPic.metadata.ts - pic.metadata.ts
+            if (
+                lastPic.metadata.ts_by_source
+                and lastPic.metadata.ts_by_source.gps
+                and pic.metadata.ts_by_source
+                and pic.metadata.ts_by_source.gps
+            ):
+                timeDelta = lastPic.metadata.ts_by_source.gps - pic.metadata.ts_by_source.gps
+            elif (
+                lastPic.metadata.ts_by_source
+                and lastPic.metadata.ts_by_source.camera
+                and pic.metadata.ts_by_source
+                and pic.metadata.ts_by_source.camera
+            ):
+                timeDelta = lastPic.metadata.ts_by_source.camera - pic.metadata.ts_by_source.camera
+            timeOutOfDelta = False if splitParams.maxTime is None else (abs(timeDelta)).total_seconds() > splitParams.maxTime
+
+            # Distance delta
+            distance = lastPic.distance_to(pic)
+            distanceOutOfDelta = False if splitParams.maxDistance is None else distance > splitParams.maxDistance
+
+            # One of deltas maxed -> create new sequence
+            if timeOutOfDelta or distanceOutOfDelta:
+                sequences.append(Sequence(currentPicList))
+                currentPicList = [pic]
+                splits.append(Split(lastPic, pic, SplitReason.time if timeOutOfDelta else SplitReason.distance))
+
+            # Otherwise, still in same sequence
+            else:
+                currentPicList.append(pic)
+
+    sequences.append(Sequence(currentPicList))
+
+    return (sequences, splits)
+
+
+def dispatch_pictures(
+    pictures: List[Picture],
+    sortMethod: Optional[SortMethod] = None,
+    mergeParams: Optional[MergeParams] = None,
+    splitParams: Optional[SplitParams] = None,
+) -> DispatchReport:
+    """
+    Dispatches a set of pictures into many sequences.
+    This function both sorts, de-duplicates and splits in sequences all your pictures.
+
+    Parameters
+    ----------
+    pictures : set of pictures to dispatch
+    sortMethod : strategy for sorting pictures
+    mergeParams : conditions for considering two pictures as duplicates
+    splitParams : conditions for considering two sequences as distinct
+
+    Returns
+    -------
+    DispatchReport : clean sequences, duplicates pictures and split reasons
+    """
+
+    # Sort
+    myPics = sort_pictures(pictures, sortMethod)
+
+    # De-duplicate
+    (myPics, dupsPics) = find_duplicates(myPics, mergeParams)
+
+    # Split in sequences
+    (mySeqs, splits) = split_in_sequences(myPics, splitParams)
+
+    return DispatchReport(mySeqs, dupsPics if len(dupsPics) > 0 else None, splits if len(splits) > 0 else None)