File Coverage

blib/lib/Geo/GoogleEarth/AutoTour.pm

Criterion	Covered	Total	%
statement	149	152	98.0
branch	32	44	72.7
condition	25	38	65.7
subroutine	18	18	100.0
pod	7	7	100.0
total	231	259	89.1

package Geo::GoogleEarth::AutoTour;
# ABSTRACT: Generate Google Earth Camera Tours from Tracks and Paths

use 5.012;
use strict;
use warnings;

use base 'Exporter';

use Carp 'croak';
use IO::Uncompress::Unzip qw( unzip $UnzipError );
use IO::Compress::Zip qw(zip $ZipError);
use XML::LibXML;
use Date::Parse 'str2time';
use Math::Trig 1.23 qw( deg2rad rad2deg great_circle_distance great_circle_bearing );

our $VERSION = '1.11'; # VERSION

our @EXPORT_OK = qw( tour kmz_to_xml xml_to_kmz load_kml read_path gather_points build_tour );

sub tour {
    my ( $input, $settings, $output ) = @_;
    croak('Input not defined') unless ( defined $input );

    my $xc = load_kml( ( ref $input ) ? kmz_to_xml($input) : $input );

    $settings //= {};
    my $doc_name = $xc->findvalue('//g:Document/g:name');
    $settings->{doc_name} //= $doc_name;

    if ( $xc->findnodes('//g:Placemark[@id="tour"]/gx:MultiTrack/gx:Track')->size ) {
        $settings->{points} = gather_points($xc);
    }
    elsif ( length $xc->findvalue('//g:Document/g:Placemark/g:LineString/g:coordinates') > 0 ) {
        $settings->{points} = read_path($xc);
    }
    else {
        croak('Input appears not to be either a track or path KML/KMZ');
    }

    my $xml = build_tour($settings);

    if ( ref $output eq 'SCALAR' ) {
        $$output = $xml;
    }
    elsif ( ref $output ) {
        xml_to_kmz( $xml, $output, $doc_name );
    }

    return $xml;
}

sub kmz_to_xml {
    my ($kmz_file_handle) = @_;
    my $buffer;
    unzip( $kmz_file_handle, \$buffer ) or die $UnzipError;
    return $buffer;
}

sub xml_to_kmz {
    my ( $xml, $kmz_file_handle ) = @_;
    zip( \$xml, $kmz_file_handle, 'Name' => 'doc.kml' ) or die $ZipError;
}

sub load_kml {
    my ($xml_input) = @_;

    my $xc;
    eval {
        $xc = XML::LibXML::XPathContext->new(
            XML::LibXML->load_xml( string => $xml_input )->documentElement
        );
    };
    croak('Unable to parse KML XML input') if ($@);

    $xc->registerNs( g => 'http://www.opengis.net/kml/2.2' );

    return $xc;
}

sub read_path {
    my ($xc) = @_;

    ( my $coords = $xc->findvalue('//g:Document/g:Placemark/g:LineString/g:coordinates') ) =~ s/^\s+|\s+$//g;
    my ( $time, $last_lat, $last_long ) = ( time, undef, undef );

    my @coords = map {
        my ( $longitude, $latitude, $altitude ) = split( /,/, $_ );
        {
            latitude  => $latitude,
            longitude => $longitude,
            altitude  => $altitude,
        };
    } split( /\s/, $coords );

    $coords[0]{time} = time;
    for ( my $i = 1; $i < @coords; $i++ ) {
        my @points = (
            deg2rad( $coords[ $i - 1 ]->{longitude} ),
            deg2rad( 90 - $coords[ $i - 1 ]->{latitude} ),
            deg2rad( $coords[$i]->{longitude} ),
            deg2rad( 90 - $coords[$i]->{latitude} ),
        );

        $coords[$i]{duration} = great_circle_distance( @points, 3956 ) / 140 * 60 * 60;
        $coords[$i]{heading} = $coords[ $i - 1 ]{heading} = rad2deg( great_circle_bearing( @points, 3956 ) );
        $coords[$i]{time} = $coords[ $i - 1 ]{time} + $coords[$i]{duration};
    }

    return \@coords;
}

sub gather_points {
    my ($xc) = @_;

    my $last_time;
    return [
        map {
            my $when    = $xc->findnodes( 'g:when', $_ );
            my $coord   = $xc->findnodes( 'gx:coord', $_ );
            my $bearing = $xc->findnodes(
                'g:ExtendedData/g:SchemaData/gx:SimpleArrayData[@name="bearing"]/gx:value',
                $_,
            );

            $when->map( sub {
                my ( $longitude, $latitude, $altitude) = split( ' ', $coord->shift->to_literal );

                my $time     = str2time( $_->to_literal );
                my $duration = ($last_time) ? $time - $last_time : undef;
                $last_time   = $time;

                {
                    latitude  => $latitude,
                    longitude => $longitude,
                    altitude  => $altitude,
                    heading   => $bearing->shift->to_literal,
                    duration  => $duration,
                    time      => $time,
                };
            } );
        } $xc->findnodes('//g:Placemark[@id="tour"]/gx:MultiTrack/gx:Track')
    ];
}

sub build_tour {
    my $settings;
    eval {
        $settings = ( ref $_[0] eq 'HASH' ) ? $_[0] : { @{ $_[0] } };
    };
    croak($@) if ($@);
    croak('Points not defined properly') unless (
        $settings->{points} and ref $settings->{points} eq 'ARRAY' and ref $settings->{points}[0] eq 'HASH'
    );

    $settings->{doc_name}            //= 'Tour';
    $settings->{tour_name}           //= 'Tour';
    $settings->{tilt}                //= 80;         # lower = deeper; higher = higher; 90 = flat
    $settings->{gap_duration}        //= 20;         # seconds
    $settings->{play_speed}          //= 20;         # higher = faster; 1 = normal
    $settings->{initial_move}        //= 2;          # seconds
    $settings->{initial_wait}        //= 5;          # seconds
    $settings->{start_trim}          //= 0;          # seconds
    $settings->{end_trim}            //= 0;          # seconds
    $settings->{altitude_adjustment} //= 100;        # feet
    $settings->{altitude_mode}       //= 'absolute'; # absolute, relativeToGround

    $settings->{altitude_mode} = 'absolute'         if ( lc( $settings->{altitude_mode} ) eq 'msl' );
    $settings->{altitude_mode} = 'relativeToGround' if ( lc( $settings->{altitude_mode} ) eq 'agl' );
    $settings->{altitude_mode} = 'relativeToGround' if ( lc( $settings->{altitude_mode} ) eq 'relative' );

    $settings->{altitude_adjustment} /= 3.28084; # convert feet into meters for use in Google Earth KML

    my $xml = XML::LibXML::Document->new( '1.0', 'UTF-8' );

    my $kml = $xml->createElement('kml');
    $kml->setAttribute( 'xmlns' => 'http://www.opengis.net/kml/2.2' );
    $kml->setAttribute( 'xmlns:gx' => 'http://www.google.com/kml/ext/2.2' );

    my $doc = $xml->createElement('Document');

    my $name = $xml->createElement('name');
    $name->appendTextNode( $settings->{doc_name} );
    $doc->appendChild($name);

    my $tour = $xml->createElement('gx:Tour');

    my $tour_name = $xml->createElement('name');
    $tour_name->appendTextNode( $settings->{tour_name} );
    $tour->appendChild($tour_name);

    my $playlist = $xml->createElement('gx:Playlist');

    my ( $wait, $total_duration ) = ( 0, 0 );
    for my $point ( @{ $settings->{points} } ) {
        next if (
            $point->{time} < $settings->{points}[0]->{time} + $settings->{start_trim}
            or
            $point->{time} > $settings->{points}[-1]->{time} - $settings->{end_trim}
        );

        $total_duration += $point->{duration} || 0;
        next if ( $total_duration < $settings->{gap_duration} );

        my $flyto = $xml->createElement('gx:FlyTo');

        my $duration = $xml->createElement('gx:duration');
        $duration->appendTextNode(
            ( defined $point->{duration} )
                ? $total_duration / $settings->{play_speed}
                : $settings->{initial_move}
        );
        $flyto->appendChild($duration);

        $total_duration = 0;

        my $mode = $xml->createElement('gx:flyToMode');
        $mode->appendTextNode('smooth');
        $flyto->appendChild($mode);

        my $camera = $xml->createElement('Camera');

        for my $node_name ( qw( latitude longitude altitude heading tilt ) ) {
            my $element = $xml->createElement($node_name);
            $element->appendTextNode(
                ( $node_name eq 'tilt' )     ? $settings->{tilt}                                       :
                ( $node_name eq 'altitude' ) ? $point->{$node_name} + $settings->{altitude_adjustment} :
                    $point->{$node_name}
            );
            $camera->appendChild($element);
        }

        my $a_mode = $xml->createElement('altitudeMode');
        $a_mode->appendTextNode( $settings->{altitude_mode} );
        $camera->appendChild($a_mode);

        $flyto->appendChild($camera);
        $playlist->appendChild($flyto);

        unless ($wait) {
            my $gx_wait = $xml->createElement('gx:Wait');

            my $element = $xml->createElement('gx:duration');
            $element->appendTextNode( $settings->{initial_wait} );
            $gx_wait->appendChild($element);

            $playlist->appendChild($gx_wait);

            $wait = 1;
        }
    }

    $tour->appendChild($playlist);
    $doc->appendChild($tour);
    $kml->appendChild($doc);
    $xml->setDocumentElement($kml);

    return $xml->toString(1);
}

1;

__END__