Tag Reader's API Reference

def decodeLatLon(data: dict, group: str, _: Callable[[str], str]) -> Tuple[Optional[float], Optional[float], List[str]]:
    """Reads GPS info from given group to get latitude/longitude as float coordinates"""

    lat, lon = None, None
    warnings = []

    if isExifTagUsable(data, f"{group}.GPSLatitude", List[Fraction]) and isExifTagUsable(data, f"{group}.GPSLongitude", List[Fraction]):
        latRaw = decodeManyFractions(data[f"{group}.GPSLatitude"])
        if len(latRaw) == 3:
            if not isExifTagUsable(data, f"{group}.GPSLatitudeRef"):
                warnings.append(_("GPSLatitudeRef not found, assuming GPSLatitudeRef is North"))
                latRef = 1
            else:
                latRef = -1 if data[f"{group}.GPSLatitudeRef"].startswith("S") else 1
            lat = latRef * (float(latRaw[0]) + float(latRaw[1]) / 60 + float(latRaw[2]) / 3600)

            lonRaw = decodeManyFractions(data[f"{group}.GPSLongitude"])
            if len(lonRaw) != 3:
                raise InvalidExifException(_("Broken GPS coordinates in picture EXIF tags"))

            if not isExifTagUsable(data, f"{group}.GPSLongitudeRef"):
                warnings.append(_("GPSLongitudeRef not found, assuming GPSLongitudeRef is East"))
                lonRef = 1
            else:
                lonRef = -1 if data[f"{group}.GPSLongitudeRef"].startswith("W") else 1
            lon = lonRef * (float(lonRaw[0]) + float(lonRaw[1]) / 60 + float(lonRaw[2]) / 3600)

    if lat is None and lon is None:
        rawLat, rawLon = None, None
        if isExifTagUsable(data, f"{group}.GPSLatitude", float) and isExifTagUsable(data, f"{group}.GPSLongitude", float):
            rawLat = float(data[f"{group}.GPSLatitude"])
            rawLon = float(data[f"{group}.GPSLongitude"])
        elif isExifTagUsable(data, f"{group}.GPSLatitude", Fraction) and isExifTagUsable(data, f"{group}.GPSLongitude", Fraction):
            rawLat = float(Fraction(data[f"{group}.GPSLatitude"]))
            rawLon = float(Fraction(data[f"{group}.GPSLongitude"]))

        if rawLat and rawLon:
            latRef = 1
            if not isExifTagUsable(data, f"{group}.GPSLatitudeRef"):
                warnings.append(_("GPSLatitudeRef not found, assuming GPSLatitudeRef is North"))
            else:
                latRef = -1 if data[f"{group}.GPSLatitudeRef"].startswith("S") else 1

            lonRef = 1
            if not isExifTagUsable(data, f"{group}.GPSLongitudeRef"):
                warnings.append(_("GPSLongitudeRef not found, assuming GPSLongitudeRef is East"))
            else:
                lonRef = -1 if data[f"{group}.GPSLongitudeRef"].startswith("W") else 1

            lat = latRef * rawLat
            lon = lonRef * rawLon

    return (lat, lon, warnings)

def decodeMakeModel(value) -> str:
    """Python 2/3 compatible decoding of make/model field."""
    if hasattr(value, "decode"):
        try:
            return value.decode("utf-8").replace("\x00", "")
        except UnicodeDecodeError:
            return value
    else:
        return value.replace("\x00", "")

def decodeManyFractions(value: str) -> List[Fraction]:
    """Try to decode a list of fractions, separated by spaces"""

    try:
        vals = [Fraction(v.strip()) for v in value.split(" ")]
        if len([True for v in vals if v.denominator == 0]) > 0:
            raise InvalidFractionException()
        return vals

    except:
        raise InvalidFractionException()

def isExifTagUsable(exif, tag, expectedType: Any = str) -> bool:
    """Is a given EXIF tag usable (not null and not an empty string)

    Args:
        exif (dict): The EXIF tags
        tag (str): The tag to check
        expectedType (class): The expected data type

    Returns:
        bool: True if not empty
    """

    try:
        if not tag in exif:
            return False
        elif expectedType == List[Fraction]:
            return isValidManyFractions(exif[tag])
        elif expectedType == Fraction:
            try:
                Fraction(exif[tag])
                return True
            except:
                return False
        elif expectedType == datetime.time:
            try:
                datetime.time.fromisoformat(exif[tag])
                return True
            except:
                return False
        elif expectedType == datetime.tzinfo:
            try:
                datetime.datetime.fromisoformat(f"2020-01-01T00:00:00{exif[tag]}")
                return True
            except:
                return False
        elif not (expectedType in [float, int] or isinstance(exif[tag], expectedType)):
            return False
        elif not (expectedType != str or len(exif[tag].strip().replace("\x00", "")) > 0):
            return False
        elif not (expectedType not in [float, int] or float(exif[tag]) is not None):
            return False
        else:
            return True
    except ValueError:
        return False

def readPictureMetadata(picture: bytes, lang_code: str = "en") -> GeoPicTags:
    """Extracts metadata from picture file

    Args:
        picture (bytes): Picture file
        lang_code (str): Language code for translating error labels

    Returns:
        GeoPicTags: Extracted metadata from picture
    """

    _ = i18n_init(lang_code)
    warnings = []
    img = pyexiv2.ImageData(picture)
    data = {}
    data.update(img.read_exif())
    data.update(img.read_iptc())
    data.update(img.read_xmp())
    width = img.get_pixel_width()
    height = img.get_pixel_height()

    imgComment = img.read_comment()
    if imgComment is not None and len(imgComment.strip()) > 0:
        data["Exif.Photo.UserComment"] = imgComment
    img.close()

    # Read Mapillary tags
    if "Exif.Image.ImageDescription" in data:
        # Check if data can be read
        imgDesc = data["Exif.Image.ImageDescription"]
        try:
            imgDescJson = json.loads(imgDesc)
            data.update(imgDescJson)
        except:
            pass

    # Sanitize charset information
    for k, v in data.items():
        if isinstance(v, str):
            data[k] = re.sub(r"charset=[^\s]+", "", v).strip()

    # Parse latitude/longitude
    lat, lon, llw = decodeLatLon(data, "Exif.GPSInfo", _)
    if len(llw) > 0:
        warnings.extend(llw)

    if lat is None:
        lat, lon, llw = decodeLatLon(data, "Xmp.exif", _)
        if len(llw) > 0:
            warnings.extend(llw)

    if lat is None and isExifTagUsable(data, "MAPLatitude", float) and isExifTagUsable(data, "MAPLongitude", float):
        lat = float(data["MAPLatitude"])
        lon = float(data["MAPLongitude"])

    # Check coordinates validity
    if lat is not None and (lat < -90 or lat > 90):
        raise InvalidExifException(_("Read latitude is out of WGS84 bounds (should be in [-90, 90])"))
    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 GPS date/time
    gpsTs, llw = decodeGPSDateTime(data, "Exif.GPSInfo", _, lat, lon)

    if len(llw) > 0:
        warnings.extend(llw)

    if gpsTs is None:
        gpsTs, llw = decodeGPSDateTime(data, "Xmp.exif", _, lat, lon)
        if len(llw) > 0:
            warnings.extend(llw)

    if gpsTs is None and isExifTagUsable(data, "MAPGpsTime"):
        try:
            year, month, day, hour, minutes, seconds, milliseconds = [int(dp) for dp in data["MAPGpsTime"].split("_")]
            gpsTs = datetime.datetime(
                year,
                month,
                day,
                hour,
                minutes,
                seconds,
                milliseconds * 1000,
                tzinfo=datetime.timezone.utc,
            )

        except Exception as e:
            warnings.append(_("Skipping Mapillary date/time as it was not recognized: {v}").format(v=data["MAPGpsTime"]))

    # 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)

        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

    # 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"])))

    # Yaw / Pitch / roll
    yaw = None
    pitch = None
    roll = None
    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, exifTag, float):
                foundValue = float(data[exifTag])
            elif isExifTagUsable(data, exifTag, Fraction):
                foundValue = float(Fraction(data[exifTag]))

            # Save found value
            if foundValue is not None:
                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")
    model = data.get("Exif.Image.Model") or data.get("MAPDeviceModel")

    if make is not None:
        make = decodeMakeModel(make).strip()

    if model is not None:
        model = decodeMakeModel(model).strip()

    if make is not None and model is not None and model.startswith(make) and len(model) > len(make):
        model = model.replace(make, "").strip()

    # Focal length
    focalLength = None
    if isExifTagUsable(data, "Exif.Image.FocalLength", Fraction):
        focalLength = float(Fraction(data["Exif.Image.FocalLength"]))
    elif isExifTagUsable(data, "Exif.Photo.FocalLength", Fraction):
        focalLength = float(Fraction(data["Exif.Photo.FocalLength"]))

    # Cropped pano data
    crop = None
    if (
        isExifTagUsable(data, "Xmp.GPano.FullPanoWidthPixels", int)
        and isExifTagUsable(data, "Xmp.GPano.FullPanoHeightPixels", int)
        and isExifTagUsable(data, "Xmp.GPano.CroppedAreaImageWidthPixels", int)
        and isExifTagUsable(data, "Xmp.GPano.CroppedAreaImageHeightPixels", int)
        and isExifTagUsable(data, "Xmp.GPano.CroppedAreaLeftPixels", int)
        and isExifTagUsable(data, "Xmp.GPano.CroppedAreaTopPixels", int)
    ):
        fw = int(data["Xmp.GPano.FullPanoWidthPixels"])
        fh = int(data["Xmp.GPano.FullPanoHeightPixels"])
        w = int(data["Xmp.GPano.CroppedAreaImageWidthPixels"])
        h = int(data["Xmp.GPano.CroppedAreaImageHeightPixels"])
        l = int(data["Xmp.GPano.CroppedAreaLeftPixels"])
        t = int(data["Xmp.GPano.CroppedAreaTopPixels"])

        if fw > w or fh > h:
            crop = CropValues(fw, fh, w, h, l, t)

    elif (
        isExifTagUsable(data, "Xmp.GPano.CroppedAreaImageWidthPixels", int)
        or isExifTagUsable(data, "Xmp.GPano.CroppedAreaImageHeightPixels", int)
        or isExifTagUsable(data, "Xmp.GPano.CroppedAreaLeftPixels", int)
        or isExifTagUsable(data, "Xmp.GPano.CroppedAreaTopPixels", int)
    ):
        raise InvalidExifException("EXIF tags contain partial cropped area metadata")

    # Type
    pic_type = None
    # 360° based on GPano EXIF tag
    if isExifTagUsable(data, "Xmp.GPano.ProjectionType"):
        pic_type = data["Xmp.GPano.ProjectionType"]
    # 360° based on known models
    elif camera.is_360(make, model, width, height):
        pic_type = "equirectangular"
    # Flat by default
    else:
        pic_type = "flat"

    # Altitude
    altitude = None
    if isExifTagUsable(data, "Exif.GPSInfo.GPSAltitude", Fraction):
        altitude_raw = int(round(float(Fraction(data["Exif.GPSInfo.GPSAltitude"]))))
        ref = -1 if data.get("Exif.GPSInfo.GPSAltitudeRef") == "1" else 1
        altitude = altitude_raw * ref

    errors = []
    missing_fields = set()
    if not lat or not lon:
        errors.append(_("No GPS coordinates or broken coordinates in picture EXIF tags"))
        if not lat:
            missing_fields.add("lat")
        if not lon:
            missing_fields.add("lon")
    if d is None:
        errors.append(_("No valid date in picture EXIF tags"))
        missing_fields.add("datetime")

    if errors:
        if len(errors) > 1:
            listOfErrors = _("The picture is missing mandatory metadata:")
            errorSep = "\n\t- "
            listOfErrors += errorSep + errorSep.join(errors)
        else:
            listOfErrors = errors[0]

        raise PartialExifException(
            listOfErrors,
            missing_fields,
            PartialGeoPicTags(
                lat,
                lon,
                d,
                heading,
                pic_type,
                make,
                model,
                focalLength,
                crop,
                exif=data,
                tagreader_warnings=warnings,
                altitude=altitude,
                pitch=pitch,
                roll=roll,
                yaw=yaw,
                ts_by_source=tsSources,
            ),
        )

    assert lon and lat and d  # at this point all those fields cannot be null
    return GeoPicTags(
        lat,
        lon,
        d,
        heading,
        pic_type,
        make,
        model,
        focalLength,
        crop,
        exif=data,
        tagreader_warnings=warnings,
        altitude=altitude,
        pitch=pitch,
        roll=roll,
        yaw=yaw,
        ts_by_source=tsSources,
    )

def format_offset(offset: Optional[timedelta]) -> str:
    """Format offset for OffsetTimeOriginal. Format is like "+02:00" for paris offset
    >>> format_offset(timedelta(hours=5, minutes=45))
    '+05:45'
    >>> format_offset(timedelta(hours=-3))
    '-03:00'
    """
    if offset is None:
        return "+00:00"
    offset_hour, remainer = divmod(offset.total_seconds(), 3600)
    return f"{'+' if offset_hour >= 0 else '-'}{int(abs(offset_hour)):02}:{int(remainer/60):02}"

def localize_capture_time(metadata: PictureMetadata, img_metadata: pyexiv2.ImageData) -> datetime:
    """
    Localize a datetime in the timezone of the picture
    If the picture does not contains GPS position, the datetime will not be modified.
    """
    assert metadata.capture_time
    dt = metadata.capture_time

    if metadata.longitude is not None and metadata.latitude is not None:
        # if the coord have been overrided, read it instead of the picture's
        lon = metadata.longitude
        lat = metadata.latitude
    else:
        exif = img_metadata.read_exif()
        try:
            raw_lon = exif["Exif.GPSInfo.GPSLongitude"]
            lon_ref = exif.get("Exif.GPSInfo.GPSLongitudeRef", "E")
            raw_lat = exif["Exif.GPSInfo.GPSLatitude"]
            lat_ref = exif.get("Exif.GPSInfo.GPSLatitudeRef", "N")
            lon = _from_dms(raw_lon) * (1 if lon_ref == "E" else -1)
            lat = _from_dms(raw_lat) * (1 if lat_ref == "N" else -1)
        except KeyError:
            return metadata.capture_time  # canot localize, returning same date

    if not lon or not lat:
        return dt  # canot localize, returning same date

    tz_name = tz_finder.timezone_at(lng=lon, lat=lat)
    if not tz_name:
        return dt  # cannot find timezone, returning same date

    tz = pytz.timezone(tz_name)

    return tz.localize(dt)

def writePictureMetadata(picture: bytes, metadata: PictureMetadata, lang_code: str = "en") -> bytes:
    """
    Override exif metadata on raw picture and return updated bytes
    """

    _ = i18n_init(lang_code)

    if not metadata.has_change():
        return picture

    img = pyexiv2.ImageData(picture)

    updated_exif: Dict[str, Any] = {}
    updated_xmp: Dict[str, Any] = {}

    if metadata.capture_time:
        if metadata.capture_time.tzinfo is None:
            metadata.capture_time = localize_capture_time(metadata, img)
        updated_exif.update(_date_exif_tags(metadata.capture_time))

    if metadata.latitude is not None:
        updated_exif["Exif.GPSInfo.GPSLatitudeRef"] = "N" if metadata.latitude > 0 else "S"
        updated_exif["Exif.GPSInfo.GPSLatitude"] = _to_exif_dms(metadata.latitude)

    if metadata.longitude is not None:
        updated_exif["Exif.GPSInfo.GPSLongitudeRef"] = "E" if metadata.longitude > 0 else "W"
        updated_exif["Exif.GPSInfo.GPSLongitude"] = _to_exif_dms(metadata.longitude)

    if metadata.picture_type is not None:
        if metadata.picture_type == PictureType.equirectangular:
            # only add GPano tags for equirectangular pictures
            updated_xmp["Xmp.GPano.ProjectionType"] = metadata.picture_type.value
            updated_xmp["Xmp.GPano.UsePanoramaViewer"] = True
        else:
            # remove GPano tags for flat picture
            updated_xmp["Xmp.GPano.ProjectionType"] = None
            updated_xmp["Xmp.GPano.UsePanoramaViewer"] = None

    if metadata.altitude is not None:
        updated_exif["Exif.GPSInfo.GPSAltitude"] = _fraction(abs(metadata.altitude))
        updated_exif["Exif.GPSInfo.GPSAltitudeRef"] = 0 if metadata.altitude >= 0 else 1

    if metadata.direction is not None:
        direction = _fraction(abs(metadata.direction.value % 360.0))
        updated_exif["Exif.GPSInfo.GPSImgDirection"] = direction
        updated_exif["Exif.GPSInfo.GPSImgDirectionRef"] = metadata.direction.ref.value
        # also write GPano tag
        updated_xmp["Xmp.GPano.PoseHeadingDegrees"] = direction

    if metadata.additional_exif:
        for k, v in metadata.additional_exif.items():
            if k.startswith("Xmp."):
                updated_xmp.update({k: v})
            elif k.startswith("Exif."):
                updated_exif.update({k: v})
            else:
                raise UnsupportedExifTagException(_("Unsupported key in additional tags ({k})").format(k=k))

    if updated_exif:
        img.modify_exif(updated_exif)
    if updated_xmp:
        img.modify_xmp(updated_xmp)

    return img.get_bytes()