NAME

Image::Synchronize::CameraOffsets - Manage time offsets for a range of times

METHODS

The module provides the following methods:

new

  $co = Image::Synchronize::CameraOffsets->new;
  $co2 = $co->new;

Creates and returns a new instance of this class.

set

  $co = $co->set($camera_id, $time, $offset);
  $co = $co->set($camera_id, $time, $offset, $file);

Declares a time offset for a particular time for a particular camera.

$camera_id is the ID of the camera that took the image for which an offset is specified.

$time is the time (either in seconds since the epoch, as for gmtime, or else as an Image::Synchronize::Timestamp) of the image for which the offset is specified.

$offset is the time offset that is valid at the specified $time. It must be either a number, or else an Image::Synchronize::Timestamp.

If it is a number, then that is the time offset in seconds.

If it is an Image::Synchronize::Timestamp, then the timezone part provides the nominal timezone that the camera clock was set to, and the clock time part provides the time offset relative to the nominal timezone.

$file is the optional file name. If it is defined, then it is used in any generated messages.

In scalar context, returns the object itself. In list context, returns the object and also a true or false value that says whether an offset for that camera and time already existed and was replaced. That second element has a false value if there was no offset yet, and also if there was already an offset but it wasn't changed.

cameras

  @cameras = $co->cameras;

Returns the IDs of the cameras for which time offsets have been registered.

camera_count

  $count = $co->camera_count;

Returns the count of cameras represented in $co.

added_time_range

  ($min_added_time, $max_added_time) = $co->added_time_range;

Returns the oldest and youngest time that have been added to $co. The timestamps are returned as Image::Synchronize::Timestamps.

get

  $offset = $co->get($camera_id, $time);
  ($offset, $file) = $co->get($camera_id, $time);

Returns a camera offset, interpreting the registered camera offsets as defining a piecewise constant function.

Camera offsets for a camera ID are registered through /set for specific times. The current method assumes that a camera offset is valid from that time until the next later time for which a camera offset was registered for the same camera ID, and that the oldest camera ofset is valid also for any earlier time.

$camera_id is the camera ID for which to return a camera offset.

$time is the time for which to return a camera offset. The time must be specified either in seconds since the epoch, as for gmtime, or else as an Image::Synchronize::Timestamp.

In scalar context, returns the requested camera offset, or undef if no offsets at all have yet been registered for that $camera_id.

In list context, returns the $offset as for the scalar case, and also returns the name of the file for which that offset was registered, if known, or undef otherwise. A file name (different from undef) is only returned if an offset was registered for exactly that $time.

get_exact

  $offset = $co->get_exact($camera_id, $time);

Returns the camera offset for the specified $time for the specified $camera_id, if a camera offset was set (through "set") for exactly that time and camera ID. Returns undef if not found.

$time is the time either in seconds since the epoch, as for gmtime, or else as an Image::Synchronize::Timestamp.

export_data

  $data = $co->export_data;

Returns a version of Image::Synchronize::CameraOffsets $co suitable for exporting. The return value is similar to

  {
    'cameraid1' =>
    {
      '2019-06-04T14:33:12' => '+1:03:15',
      '2019-06-05T08:11:43' => '+1:03:15'
    },
    'cameraid2' =>
    {
      '2019-01-01T00:00:00' => '+2:00',
      '2019-06-05T08:11:43' => '+2:00'
    },
  }

parse

  $co = $co->parse($data);

Parses camera offsets information from text $data into Image::Synchronize::CameraOffsets $co, replacing any earlier contents of $co. The text is expected to be in the format that "stringify" produces. Returns the object.

relevant_part

  $relevant = $co->relevant_part;

Extracts the part of the camera offsets $co that was accessed. The results include only those camera IDs that were accessed through "set" or "get" since the last call to "parse", and for each of those camera IDs only the smallest time range that was accessed for that camera ID.

The return value is a HASH reference, similar to

  {
    'CameraID1' => {
      '2018-03-10T17:44:22' => 76,
      '2018-05-02T12:55:52' => -15,
      '2018-06-22T09:22:15' => -15
    },
  }

The keys are camera IDs and their

stringify

  $text = $co->stringify;

Returns the exportable contents of Image::Synchronize::CameraOffsets $co in YAML format. The return value is similar to

    cameraid1:
      2019-06-04T14:33:12: +1:03:15
      2019-06-05T08:11:43: +1:03:15
    cameraid2:
      2019-01-01T00:00:00: +2:00
      2019-06-05T08:11:43: +2:00

DEPENDENCIES

This module uses the following non-core Perl module:

• Image::Synchronize::Timestamp

• namespace::clean

• YAML::Any

AUTHOR

Louis Strous <LS@quae.nl>

LICENSE AND COPYRIGHT

Copyright (c) 2018 - 2020 Louis Strous.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Image::Synchronize

perl -MCPAN -e shell
install Image::Synchronize