NAME
Net::Flickr::Backup - OOP for backing up your Flickr photos locally
SYNOPSIS
use Net::Flickr::Backup;
use Log::Dispatch::Screen;
my $flickr = Net::Flickr::Backup->new($cfg);
my $feedback = Log::Dispatch::Screen->new('name' => 'info',
'min_level' => 'info');
$flickr->log()->add($feedback);
$flickr->backup();
DESCRIPTION
OOP for backing up your Flickr photos locally.
OPTIONS
Options are passed to Net::Flickr::Backup using a Config::Simple object
or a valid Config::Simple config file. Options are grouped by "block".
flickr
* api_key
String. *required*
A valid Flickr API key.
* api_secret
String. *required*
A valid Flickr Auth API secret key.
* auth_token
String. *required*
A valid Flickr Auth API token.
The api_handler defines which XML/XPath handler to use to process
API responses.
* LibXML
Use XML::LibXML.
* XPath
Use XML::XPath.
backup
* photos_root
String. *required*
The root folder where you want photographs to be stored. Individual
files are named using the following pattern :
B<photos_root>/B<YYYY>/B<MM>/B<DD>/B<YYYYMMDD>-B<photo_id>-B<clean_title>_B<size>.jpg
Where the various components are :
* YYYYMMDD
photo[@id=123]/dates/@taken
* photo_id
photo/@id
* clean_title
photo[@id=123]/title
Unicode characters translated in to ASCII (using
Text::Unidecode) and the entire string is stripped anything that
is not an alphanumeric, underbar, dash or a square bracket.
* size
Net::Flickr::Backup will attempt to fetch not only the original
file uploaded to Flickr but also, depending on your config
options, the medium and square versions. Filenames will be
modified as follows :
* original
The original photo you uploaded to the Flickr servers. No
extension is added.
* medium
These photos are scaled to 500 pixels at the longest
dimension. A _m extension is added.
* medium_640
These photos are scaled to 640 pixels at the longest
dimension. A _z extension is added.
* square
These photos are to cropped to 75 x 75 pixels at the center.
A _s extension is added.
* site_mp4
The MP4 version of a video uploaded to Flickr. A _site
extension is added.
* video_original
An original video uploaded to Flickr. No extentsion is
added.
* fetch_original
Boolean.
Retrieve the "original" version of a photo from the Flickr servers.
Default is true.
* fetch_video_original
Boolean.
Retrieve the "original" version of a video from the Flickr servers.
Default is true.
* fetch_medium
Boolean.
Retrieve the "medium" version of a photo from the Flickr servers;
these photos have been scaled to 500 pixels at the longest
dimension.
Default is false.
* fetch_medium_640
Boolean.
Retrieve the "medium" version of a photo from the Flickr servers;
these photos have been scaled to 640 pixels at the longest
dimension.
Default is false.
* fetch_square
Boolean.
Retrieve the "square" version of a photo from the Flickr servers;
these photos have been cropped to 75 x 75 pixels at the center.
Default is false.
* fetch_site_mp4
Boolean.
Retrieve the "site MP4" version of a video from the Flickr servers;
Default is false.
* scrub_backups
Boolean.
If true then, for each Flickr photo ID backed up, the library will
check backup.photos_root for images (and metadata files) with a
matching ID but a different name. Matches will be deleted.
* force
Boolean.
Force a photograph to be backed up even if it has not changed.
Default is false.
rdf
* do_dump
Boolean.
Generate an RDF description for each photograph. Descriptions are
written to disk in separate files.
Default is false.
* rdfdump_root
String.
The path where RDF data dumps for a photo should be written. The
default is the same path as backup.photos_root.
File names are generated with the same pattern used to name
photographs.
* rdfdump_inline
Boolean.
Set to true if you want the RDF dump for a photo to be stored in the
file's JPEG COM block. RDF data will only be stored (for the time
being) in the original image file and not any of the scaled
versions.
This option will only work for JPEG files and is still experimental.
It may change or, you know, not always work. Using Adobe's XMP spec
is on the list of things to poke at so if you've got any suggestions
on the subject, they'd be welcome.
Default is false.
* photos_alias
String.
If defined this string is applied as regular expression substitution
to backup.photos_root.
Default is to append the file:/ URI protocol to a path.
* query_geonames
Boolean.
If true and a photo has geodata (latitude, longitude) associated
with it, then the geonames.org database will be queried for a
corresponding match. Data will be added as properties of the photo's
geo:Point description. For example :
<geo:long>-122.025151</geo:long>
<flickr:accuracy>16</flickr:accuracy>
<acl:access>visbility</acl:access>
<geo:lat>37.417839</geo:lat>
<acl:accessor>public</acl:accessor>
</geo:Point>
<geoname:featureCode>PPLX</geoname:featureCode>
<geoname:countryCode>US</geoname:countryCode>
<geoname:regionCode>CA</geoname:regionCode>
<geoname:region>California</geoname:region>
<geoname:city>Santa Clara</geoname:city>
<geoname:gtopo30>2</geoname:gtopo30>
</geoname:Feature>
iptc
* do_dump
Boolean.
If true, then a limited set of metadata associated with a photo will
be stored as IPTC information.
A photo's title is stored as the IPTC Headline, description as
Caption/Abstract and tags are stored in one or more Keyword headers.
Per the IPTC 7901 spec, all text is converted to the ISO-8859-1
character encoding.
For example :
exiv2 -pi /home/asc/photos/2006/06/20/20060620-171674319-mie.jpg
Iptc.Application2.RecordVersion Short 1 2
Iptc.Application2.Keywords String 11 cameraphone
Iptc.Application2.Keywords String 15 "san francisco"
Iptc.Application2.Keywords String 5 filtr
Iptc.Application2.Keywords String 3 mie
Iptc.Application2.Keywords String 20 upcoming:event=77752
Iptc.Application2.Headline String 3 Mie
Default is false.
search
Any valid parameter that can be passed to the *flickr.photos.search*
method except 'user_id' which is pre-filled with the user_id that
corresponds to the flickr.auth_token token.
modified_since
String.
This specifies a time-based limiting criteria for fetching photos.
The syntax is (n)(modifier) where (n) is a positive integer and
(modifier) may be one of the following :
* h Fetch photos that have been modified in the last (n) hours.
* d Fetch photos that have been modified in the last (n) days.
* w Fetch photos that have been modified in the last (n) weeks.
* M Fetch photos that have been modified in the last (n) months.
PACKAGE METHODS
__PACKAGE__->new($cfg)
Returns a *Net::Flickr::Backup* object.
OBJECTS METHODS YOU SHOULD CARE ABOUT
$obj->backup()
Returns true or false.
OBJECT METHODS YOU MAY CARE ABOUT
$obj->backup_photo($id,$secret)
Backup an individual photo. This method is called internally by
*backup*.
$obj->scrub()
Returns true or false.
$obj->cancel_backup()
Cancel the backup process as soon as the current photo backup is
complete.
$obj->register_callback($name, \&func)
This method is still considered experimental and may be removed.
Valid callback triggers are :
* start_backup_queue
The list of photos to be backed up is pulled from the Flickr servers
is done in batches. This trigger is invoked for the first successful
result set.
The callback function will be passed a *XML::XPath* representation
of the result document returned by the Flickr API.
* finish_backup_queue
This trigger is invoked after the last photo has been backed up.
* start_backup_photo
This trigger is invoked before the object's backup_photo method is
called.
The callback function will be passed a *XML::XPath* representation
of the current photo, as returned by the Flickr API.
* finish_backup_photo
This trigger is invoked after the object's backup_photo method is
called.
The callback function will be passed a *XML::XPath* representation
of the current photo, as returned by the Flickr API, followed by a
boolean indicating whether or not the backup was successful.
Returns true or false, if *$func* is not a valid code reference.
$obj->namespaces()
Returns a hash ref of the prefixes and namespaces used by
*Net::Flickr::RDF*
The default key/value pairs are :
dcterms
exif
exifi
flickr
x-urn:flickr:
foaf
rdfs
skos
*Net::Flickr::Backup* adds the following namespaces :
computer
x-urn:$OSNAME: (where $OSNAME is the value of the English.pm $OSNAME
variable.
$obj->namespace_prefix($uri)
Return the namespace prefix for *$uri*
$obj->uri_shortform($prefix,$name)
Returns a string in the form of *prefix*:*property*. The property is the
value of $name. The prefix passed may or may be the same as the prefix
returned depending on whether or not the user has defined or redefined
their own list of namespaces.
The prefix passed to the method is assumed to be one of prefixes in the
default list of namespaces.
$obj->make_photo_triples(\%data)
Returns an array ref of array refs of the meta data associated with a
photo (*%data*).
If any errors are unencounter an error is recorded via the log method
and the method returns undef.
$obj->namespace_prefix($uri)
Return the namespace prefix for *$uri*
$obj->uri_shortform($prefix,$name)
Returns a string in the form of *prefix*:*property*. The property is the
value of $name. The prefix passed may or may be the same as the prefix
returned depending on whether or not the user has defined or redefined
their own list of namespaces.
The prefix passed to the method is assumed to be one of prefixes in the
default list of namespaces.
$obj->api_call(\%args)
Valid args are :
* method
A string containing the name of the Flickr API method you are
calling.
* args
A hash ref containing the key value pairs you are passing to
*method*
If the method encounters any errors calling the API, receives an API
error or can not parse the response it will log an error event, via the
log method, and return undef.
Otherwise it will return a *XML::LibXML::Document* object (if
XML::LibXML is installed) or a *XML::XPath* object.
$obj->log()
Returns a *Log::Dispatch* object.
EXAMPLES
CONFIG FILES
This is an example of a Config::Simple file used to back up photos
tagged with 'cameraphone' from Flickr
[flickr]
api_key=asd6234kjhdmbzcxi6e323
api_secret=s00p3rs3k3t
auth_token=123-omgwtf4u
api_handler=LibXML
[search]
tags=cameraphone
per_page=500
[backup]
photos_root=/home/asc/photos
scrub_backups=1
fetch_medium=1
fetch_square=1
force=0
[rdf]
do_dump=1
rdfdump_root=/home/asc/photos
RDF
This is an example of an RDF dump for a photograph backed up from Flickr
(using Net::Flickr::RDF) :
<?xml version='1.0'?>
<rdf:RDF
xmlns:place="x-urn:flickr:place:"
xmlns:mt="x-urn:flickr:machinetag:"
xmlns:flickr="x-urn:flickr:"
>
<foaf:mbox_sha1sum>2fc2c76d7634d1a6446b1898bf5471205ed3d0cb</foaf:mbox_sha1sum>
<foaf:name></foaf:name>
<foaf:nick>thincvox</foaf:nick>
</flickr:user>
<skos:altLabel>filtr</skos:altLabel>
<skos:prefLabel rdf:resource="filtr:process=filtr"/>
</flickr:tag>
<geoname:featureCode>PPLX</geoname:featureCode>
<geoname:countryCode>US</geoname:countryCode>
<geoname:regionCode>CA</geoname:regionCode>
<geoname:gtopo30>58</geoname:gtopo30>
<geoname:region>State of California</geoname:region>
<geoname:city>San Francisco County</geoname:city>
</geoname:Feature>
<mt:predicate>feature</mt:predicate>
<mt:namespace>geonames</mt:namespace>
</flickr:machinetag>
<dcterms:relation>Original</dcterms:relation>
<exifi:height>1944</exifi:height>
<exifi:width>2592</exifi:width>
</dcterms:StillImage>
<skos:prefLabel>cameraphone</skos:prefLabel>
</flickr:tag>
<skos:prefLabel>filtr</skos:prefLabel>
</flickr:tag>
<exif:flash>Flash did not fire, auto mode</exif:flash>
<exif:digitalZoomRatio>100/100</exif:digitalZoomRatio>
<exif:isoSpeedRatings>100</exif:isoSpeedRatings>
<exif:pixelXDimension>2592</exif:pixelXDimension>
<exif:apertureValue>297/100</exif:apertureValue>
<exif:pixelYDimension>1944</exif:pixelYDimension>
<exif:focalLength>5.6 mm</exif:focalLength>
<exif:dateTimeDigitized>2007-05-30T15:10:01PDT</exif:dateTimeDigitized>
<exif:colorSpace>sRGB</exif:colorSpace>
<exif:fNumber>f/2.8</exif:fNumber>
<exif:dateTimeOriginal>2007-05-30T15:10:01PDT</exif:dateTimeOriginal>
<exif:shutterSpeedValue>4351/1000</exif:shutterSpeedValue>
<exif:exposureTime>0.049 sec (49/1000)</exif:exposureTime>
</rdf:Description>
<skos:prefLabel>san francisco</skos:prefLabel>
<skos:altLabel>sanfrancisco</skos:altLabel>
</flickr:tag>
<skos:prefLabel>sanfrancisco</skos:prefLabel>
</flickr:tag>
<dcterms:relation>Medium</dcterms:relation>
<exifi:height>375</exifi:height>
<exifi:width>500</exifi:width>
</dcterms:StillImage>
<skos:altLabel>5405296</skos:altLabel>
<skos:prefLabel rdf:resource="geonames:feature=5405296"/>
</flickr:tag>
<skos:prefLabel>cameraphone</skos:prefLabel>
</flickr:tag>
<dc:description></dc:description>
<dc:title>LOG (2007)</dc:title>
</flickr:photoset>
<dc:identifier>6065-522214395-72157600293655654</dc:identifier>
<dc:created>2007-05-31T14:54:25</dc:created>
<a:body>Kittens!</a:body>
</flickr:comment>
<foaf:mbox_sha1sum>587a68f90c4030a9b0c7d8ca6ff8549a8b40e5cd</foaf:mbox_sha1sum>
<foaf:name>Aaron Straup Cope</foaf:name>
<foaf:nick>straup</foaf:nick>
</flickr:user>
<skos:altLabel>n95</skos:altLabel>
<skos:prefLabel rdf:resource="ph:camera=n95"/>
</flickr:tag>
<rdf:Description rdf:about="x-urn:flickr:comment">
</rdf:Description>
<dc:identifier>6065-522214395-72157600295486776</dc:identifier>
<dc:created>2007-06-01T00:19:05</dc:created>
</flickr:comment>
<skos:altLabel>5405296</skos:altLabel>
<skos:prefLabel rdf:resource="geonames:feature=5405296"/>
</flickr:tag>
<mt:predicate>process</mt:predicate>
<mt:namespace>filtr</mt:namespace>
</flickr:machinetag>
<mt:predicate>debug</mt:predicate>
<mt:namespace>geo</mt:namespace>
</flickr:machinetag>
<filtr:process>filtr</filtr:process>
<nfr_geo:debug>namespace test</nfr_geo:debug>
<acl:access>visbility</acl:access>
<dc:title>Untitled #1180563722</dc:title>
<ph:camera>n95</ph:camera>
<dc:rights>All rights reserved.</dc:rights>
<acl:accessor>public</acl:accessor>
<dc:description></dc:description>
<dc:created>2007-05-30T15:10:01-0700</dc:created>
<dc:dateSubmitted>2007-05-30T15:18:39-0700</dc:dateSubmitted>
<geonames:feature>5405296</geonames:feature>
</flickr:photo>
<dcterms:relation>Thumbnail</dcterms:relation>
<exifi:height>75</exifi:height>
<exifi:width>100</exifi:width>
</dcterms:StillImage>
<rdf:Description rdf:about="x-urn:flickr:machinetag">
</rdf:Description>
<geo:long>-122.401937</geo:long>
<acl:access>visbility</acl:access>
<geo:lat>37.794694</geo:lat>
<flickr:accuracy>16</flickr:accuracy>
<acl:accessor>public</acl:accessor>
</geo:Point>
<skos:altLabel>filtr</skos:altLabel>
<skos:prefLabel rdf:resource="filtr:process=filtr"/>
</flickr:tag>
<skos:altLabel>n95</skos:altLabel>
<skos:prefLabel rdf:resource="ph:camera=n95"/>
</flickr:tag>
<rdf:Description rdf:about="#">
<dcterms:hasVersion>2.0:1180823550</dcterms:hasVersion>
<dc:created>2007-06-02T15:32:30-0700</dc:created>
</rdf:Description>
<skos:prefLabel>filtr</skos:prefLabel>
</flickr:tag>
<skos:altLabel>namespace test</skos:altLabel>
<skos:prefLabel rdf:resource="geo:debug=namespace test"/>
<skos:altLabel rdf:resource="geo:debug=namespacetest"/>
</flickr:tag>
<dcterms:relation>Small</dcterms:relation>
<exifi:height>180</exifi:height>
<exifi:width>240</exifi:width>
</dcterms:StillImage>
<rdf:Description rdf:about="x-urn:flickr:user">
</rdf:Description>
<mt:predicate>camera</mt:predicate>
<mt:namespace>ph</mt:namespace>
</flickr:machinetag>
<dcterms:relation>Square</dcterms:relation>
<exifi:height>75</exifi:height>
<exifi:width>75</exifi:width>
</dcterms:StillImage>
<dcterms:relation>Large</dcterms:relation>
<exifi:height>768</exifi:height>
<exifi:width>1024</exifi:width>
</dcterms:StillImage>
<place:county>San Francisco</place:county>
<place:country>United States</place:country>
<place:region>California</place:region>
<place:locality>San Francisco</place:locality>
</flickr:place>
<skos:altLabel>namespace test</skos:altLabel>
<skos:prefLabel rdf:resource="geo:debug=namespacetest"/>
</flickr:tag>
</rdf:RDF>
VERSION
3.1
DATE
$Date: 2010/12/19 19:06:56 $
AUTHOR
Aaron Straup Cope <ascope@cpan.org>
CONTRIBUTORS
Thomas Sibley <tsibley@cpan.org>
SEE ALSO
Net::Flickr::API
Net::Flickr::RDF
Config::Simple
BUGS
LICENSE
Copyright (c) 2005-2008 Aaron Straup Cope. All Rights Reserved.
This is free software. You may redistribute it and/or modify it under
the same terms as Perl itself.
