API Documentation
VidTransGeoTag
read_track_csv()
Read GPS track from CSV file and convert to GeoDataFrame.
This method reads a CSV file containing GPS track data and converts it into a GeoDataFrame with time and point geometry columns. It attempts to automatically detect column names for latitude, longitude and time data, or uses user-specified column names.
Returns:
| Type | Description |
|---|---|
GeoDataFrame
|
A GeoDataFrame with the following columns: - time : datetime Timestamp for each point, with any specified offset added - geometry : Point Point geometry containing longitude and latitude coordinates |
Raises:
| Type | Description |
|---|---|
ValueError
|
If latitude, longitude or time columns cannot be found in the CSV file |
Notes
The method looks for common column names for latitude (e.g., 'latitude', 'lat', 'y'), longitude (e.g., 'longitude', 'lon', 'x') and time (e.g., 'time', 'timestamp', 'datetime'). Column names are case-insensitive.
The resulting GeoDataFrame uses the WGS84 coordinate reference system (EPSG:4326).
get_video_start_time_and_duration(video_path)
Get the creation time and duration of a video file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
video_path
|
Path
|
Path object representing the location of the video file. |
required |
Returns:
| Type | Description |
|---|---|
tuple[datetime, float]
|
A tuple containing: - creation_time: The video creation time as datetime - duration: Duration of the video as timedelta |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If there's an error probing the video file with ffmpeg. |
ValueError
|
If the creation time or duration information is not found in the video metadata. |
get_video_frame_rate(video_path)
Get the frame rate of a video file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
video_path
|
Path
|
Path object representing the location of the video file. |
required |
Returns:
| Type | Description |
|---|---|
float
|
The frame rate in frames per second. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If there's an error probing the video file with ffmpeg. |
ValueError
|
If the frame rate information is not found in the video metadata. |
filter_gdf_on_distance(gdf, epsg=None, min_distance=1.0, outlier_distance=1000.0)
Filter a geodataframe by including samples only when position has changed significantly.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gdf
|
GeoDataFrame
|
Input geodataframe to filter |
required |
epsg
|
int
|
EPSG code for CRS to measure distance in. If None, best matching UTM zone will be used |
None
|
min_distance
|
float
|
Minimum change in position required for next sample to be included. Units defined by CRS |
1.0
|
outlier_distance
|
float
|
Maximum allowed distance between consecutive points. Points with larger distances are excluded. Units defined by CRS |
1000.0
|
Returns:
| Type | Description |
|---|---|
GeoDataFrame
|
Filtered geodataframe containing only points that meet the distance criteria |
Notes
When epsg is None, the function automatically selects the UTM zone based on data centroid
_normalize_datetime(dt)
Normalize datetime to UTC if timezone aware, or add UTC if naive.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime or Timestamp
|
The datetime object to normalize |
required |
Returns:
| Type | Description |
|---|---|
datetime
|
Normalized datetime object in UTC |
check_video_overlaps_track(video_path, verbose=False)
Check if video timestamps overlap with track timestamps.
This function compares the start and end timestamps of a video file with the timestamps in the track data to determine if there is any temporal overlap.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
video_path
|
Path
|
Path to the video file to check |
required |
verbose
|
bool
|
If True, prints detailed information about the temporal relationship between video and track, by default False |
False
|
Returns:
| Type | Description |
|---|---|
bool
|
True if video timestamps overlap with track timestamps, False otherwise |
get_track_points_within_video(video_path)
Identify track positions contained within video time window
Returns:
| Type | Description |
|---|---|
GeoDataFrame
|
GeoDataFrame containing only rows whose timestamps overlap with video time window |
images_from_video(video_input_file, video_frame_rate, image_base_name, image_output_dir, times, batch_size=20, image_quality=5, overwrite=True)
Extract multiple images from video at given times
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
video_input_file
|
str or Path
|
Path to input video file |
required |
image_base_name
|
str
|
Base name for output image files (used during renaming) |
required |
image_output_dir
|
Path
|
Directory in which to output images |
required |
times
|
list or array - like
|
List of timestamps in seconds to extract frames from |
required |
batch_size
|
int
|
Number of time points to process per ffmpeg call, by default 20 |
20
|
image_quality
|
int
|
FFmpeg quality parameter (1-31), by default 5. Lower values result in higher quality images. |
5
|
overwrite
|
bool
|
Whether to overwrite existing files, by default True |
True
|
Returns:
| Type | Description |
|---|---|
list
|
List of generated output filenames |
_rename_image_files_with_timestamp(image_files, image_base_name, image_times)
Rename image files, combining a base name with a time stamp.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image_files
|
list[Path]
|
List of image file paths to be renamed. |
required |
image_base_name
|
str
|
Base name (typically the video file stem) to prepend to the timestamp. |
required |
image_times
|
NDArray
|
Array of time deltas (in seconds) relative to video start time. |
required |
Returns:
| Type | Description |
|---|---|
list[Path]
|
List of renamed image file paths. |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If any specified image file does not exist. |
Exception
|
If any error occurs during the renaming process. |
extract_geotagged_images_from_video(video_path, image_output_folder, gpkg_path=None, filter_min_distance_m=None)
Extract geotagged images from video at timestamps overlapping with track
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
video_path
|
Path
|
Path to input video file |
required |
image_output_folder
|
Path
|
Path to output folder where images will be saved |
required |
Returns:
| Type | Description |
|---|---|
list
|
List of generated output filenames |
batch_extract_geotagged_images_from_videos(video_folder, image_output_folder, gpkg_path=None)
Process multiple videos to extract and geotag frames at track locations.
This method processes all MP4 video files in the specified folder, extracting frames at timestamps that match GPS track points and embedding the corresponding location data in each image's EXIF metadata.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
video_folder
|
Path
|
Path to folder containing MP4 video files to process |
required |
image_output_folder
|
Path
|
Path to folder where extracted and geotagged images will be saved. Images are named using pattern: videoname_MMMmSSsMMMs.jpg where: - MMM = minutes (zero-padded to 3 digits) - SS = seconds (zero-padded to 2 digits) - MMM = milliseconds (zero-padded to 3 digits) |
required |
gpkg_path
|
Optional[Path]
|
If provided, saves the combined GeoDataFrame to this path as a GeoPackage file |
None
|
Returns:
| Type | Description |
|---|---|
GeoDataFrame
|
Combined GeoDataFrame containing extracted image locations and metadata with columns: - geometry : Point Location where image was taken (from GPS track) - time : datetime Timestamp when image was taken - image_file : Path Path to the extracted and geotagged image file |
Notes
- Only processes .mp4 files in the video folder
- Only extracts frames from videos that temporally overlap with the GPS track
- Returns empty GeoDataFrame if no valid data is found
- Uses EPSG:4326 (WGS84) coordinate reference system
merge_videos_in_directory(input_dir, output_file, compress_by_transcoding=False, transcoding_quality_crf=28)
Merges all MP4 video files in the given directory into one file without transcoding. Assumes the files (sorted alphabetically) are from a single recording. The creation_time metadata from the first file is transferred to the merged output.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_dir
|
Path
|
Directory containing the MP4 video files. |
required |
output_file
|
Path
|
Path to the merged output video file. |
required |
compress_by_transcoding
|
bool
|
If True, the videos are compressed by transcoding to H.264 using libx264, by default False |
False
|
transcoding_quality_crf
|
int
|
Constant Rate Factor (CRF) for libx264 (0-51, lower is higher quality), by default 28. Ignored if compress_by_transcoding is False. |
28
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If no MP4 files are found in the provided directory. |
RuntimeError
|
If probing the first file fails or ffmpeg fails to merge the videos. |
Notes
- The constant rate factor (CRF) controls the quality of the output video. A value of 23 is often considered a good compromise between quality and file size. A default of 28 is used here for slightly more aggressive compression.
write_geotag_to_image(image_path, lat, lon, altitude=None, timestamp=None)
Write GPS coordinates to image EXIF metadata.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image_path
|
Path
|
Path to the image file |
required |
lat
|
float
|
Latitude in decimal degrees |
required |
lon
|
float
|
Longitude in decimal degrees |
required |
altitude
|
float
|
Altitude in meters |
None
|
timestamp
|
datetime
|
GPS timestamp to write |
None
|
Notes
Uses exiftool to write the following GPS tags: - GPSLatitude/GPSLatitudeRef - GPSLongitude/GPSLongitudeRef - GPSAltitude/GPSAltitudeRef (if altitude provided) - GPSDateStamp/GPSTimeStamp (if timestamp provided)