Class LrPhoto
Objects of this type are returned by various functions of LrCatalog and LrExportSession.
Summary
LrMetadataProvider script.LrCatalog) The catalog object that contains this photo.LrPhoto) The master photo from which this virtual copy is derived.LrPhoto) All members of the stack that this photo is in.LrPhoto) All virtual copies of this photo.Functions
- photo:checkPhotoAvailability()
-
Reports whether this photo is believed to be present on disk at this time. This is not a guarantee that the photo exists (as volumes might be disconnected at any time), but a reasonably good estimate of the current status.
- If this function returns true, proceed with your file operation, but be prepared for failure. The file might still be missing.
- If this function returns false, skip your file operation. The odds are good that the file is in fact missing.
Must be called from within one of the
catalog:with___AccessDogates.First supported in version 2.0 of the Lightroom SDK.
Return value
(Boolean) True if file is thought to exist at this time. - photo:getFormattedMetadata( key )
-
Retrieves display-formatted metadata from this photo. Metadata is formatted as is shown in the metadata panel. The returned value strings are formatted for display; you should not attempt to parse them.
Must be called from within one of the
catalog:with___AccessDogates.First supported in version 1.3 of the Lightroom SDK.
Parameters
- 1. key
- (string) Which metadata item to retrieve. These valid keys return these values:
- keywordTags: (string) The list of keywords as shown in the Keyword Tags panel (with Enter Keywords selected)
- keywordTagsForExport: (string) The list of keywords as shown in the Keyword Tags panel (with Will Export selected). First supported as of Lightroom 2.0.
- fileName: (string) The leaf name of the file (for example, "myFile.jpg")
- copyName: (string) The name associated with this copy
- folderName: (string) The name of the folder the file is in
- fileSize: (string) The formatted size of the file (for example, "6.01 MB")
- fileType: (string) The user-visible file type (DNG, RAW, etc.)
- rating: (number) The user rating of the file (number of stars)
- label: (string) The name of assigned color label
- title: (string) The title of photo
- caption: (string) The caption for photo
- dimensions: (string) The original dimensions of file (for example, "3072 x 2304")
- exposure: (string) The exposure summary (for example, "1/60 sec at f/2.8")
- shutterSpeed: (string) The shutter speed (for example, "1/60 sec")
- aperture: (string) The aperture (for example, "f/2.8")
- brightnessValue: (string) The brightness value (HELP: need an example)
- exposureBias: (string) The exposure bias/compensation (for example, "-2/3 EV")
- flash: (string) Whether the flash fired or not (for example, "Did fire")
- exposureProgram: (string) The exposure program (for example, "Aperture priority")
- meteringMode: (string) The metering mode (for example, "Pattern")
- isoSpeedRating: (string) The ISO speed rating (for example, "ISO 200")
- focalLength: (string) The focal length of lens as shot (for example, "132 mm")
- focalLength35mm: (string) The focal length as 35mm equivalent (for example, "211 mm")
- lens: (string) The lens (for example, "28.0-135.0 mm")
- subjectDistance: (string) The subject distance (for example, "3.98 m")
- dateTimeOriginal: (string) The date and time of capture (for example, "09/15/2005 17:32:50") Formatting can vary based on the user's localization settings
- dateTimeDigitized: (string) date and time of scanning (for example, "09/15/2005 17:32:50") Formatting can vary based on the user's localization settings
- dateTime: (string) adjusted date and time (for example, "09/15/2005 17:32:50") Formatting can vary based on the user's localization settings
- cameraMake: (string) The camera manufacturer
- cameraModel: (string) The camera model
- cameraSerialNumber: (string) The camera serial number
- artist: (string) The artist's name
- software: (string) The software used to process/create photo
- gps: (string) The location of this photo (for example, "37°56'10" N 27°20'42" E")
- gpsAltitude: (string) The GPS altitude for this photo (for example, "82.3 m")
- creator
- creatorJobTitle
- creatorAddress
- creatorCity
- creatorStateProvince
- creatorPostalCode
- creatorCountry
- creatorPhone
- creatorEmail
- creatorUrl
- headline
- iptcSubjectCode
- descriptionWriter
- iptcCategory
- iptcOtherCategories
- dateCreated: (string) The IPTC-formatted creation date (for example, "2005-09-20T15:10:55Z")
- intellectualGenre
- scene
- location
- city
- stateProvince
- country
- isoCountryCode
- jobIdentifier
- instructions
- provider
- source
- copyright
- rightsUsageTerms
- copyrightInfoUrl
Return value
(string) The formatted-string value of the specified metadata property, or nil if not applicable - photo:getPropertyForPlugin( plugin, fieldName, optVersion )
-
Gets plug-in-specific data for this photo, as declared in an
LrMetadataProviderscript.Must be called from within one of the
catalog:with___AccessDogates.First supported in version 2.0 of the Lightroom SDK.
Parameters
- 1. plugin
- (string or _PLUGIN) Your _PLUGIN object or the unique identifying string for the plug-in that declares this field.
- 2. fieldName
- (string) The metadata field name.
- 3. optVersion
- (optional, number) The version number for the field (only valid in schema update handlers).
Return value
The value for this field, if any. - photo:getRawMetadata( key )
-
Retrieves unformatted metadata from this photo.
Must be called from within one of the
catalog:with___AccessDogates.First supported in version 1.3 of the Lightroom SDK.
Parameters
- 1. key
- (string) The metadata item to retrieve. These valid keys return these values:
- fileFormat: (string) The format of the file. One of 'RAW', 'DNG', 'JPG', 'PSD', or 'TIFF'. First supported in version 2.0 of the Lightroom SDK.
- fileSize: (number) The size of the file in bytes
- rating: (number) The user rating of the file (number of stars)
- dimensions: (table) The dimensions of file (for example, { width = 2304, height = 3072 } )
- width: (number) The width of the original source photo in pixels. First supported in version 2.0 of the Lightroom SDK.
- height: (number) The height of the original source photo in pixels. First supported in version 2.0 of the Lightroom SDK.
- aspectRatio: (number) The aspect ratio of the photo (defined as width / height). (For example, a standard 35mm photo in landscape mode will return 1.5.). First supported in version 2.0 of the Lightroom SDK.
- isCropped: (Boolean) True if the photo has been cropped in Lightroom from its original dimensions. First supported in version 2.0 of the Lightroom SDK.
- shutterSpeed: (number) The shutter speed, in seconds (for example, 1/60 sec = 0.016666)
- aperture: (number) The denominator of the aperture (for example, 2.8)
- exposureBias: (number) The exposure bias/compensation (for example, -0.666666)
- flash: (Boolean) Whether flash fired or not (true = flash fired; false = flash did not fire; nil = unknown)
- isoSpeedRating: (number) The ISO speed rating (for example, 200)
- focalLength: (number) The focal length of lens as shot, in millimeters (for example, 132)
- focalLength35mm: (number) The focal length as 35mm equivalent, in millimeters (for example, 211.2)
- dateTimeOriginal: (number) The date and time of capture (seconds since midnight GMT January 1, 2001)
- dateTimeDigitized: (number) The date and time of scanning (seconds since midnight GMT January 1, 2001)
- dateTime: (number) The adjusted date and time (seconds since midnight GMT January 1, 2001)
- dateTimeOriginalISO8601: (string) The date and time of capture (ISO 8601 string format). First supported in version 2.0 of the Lightroom SDK.
- dateTimeDigitizedISO8601: (string) The date and time of scanning (ISO 8601 string format). First supported in version 2.0 of the Lightroom SDK.
- dateTimeISO8601: (string) The adjusted date and time (ISO 8601 string format). First supported in version 2.0 of the Lightroom SDK.
- gps: (table) The location of this photo (for example, { latitude = 37.9362, longitude = 27.3451 } )
- gpsAltitude: (number) The GPS altitude for this photo, in meters (for example, 82.317)
- lastEditTime: (number) The date and time of the last edit to this photo (seconds since midnight GMT January 1, 2001). First supported in version 2.0 of the Lightroom SDK.
- editCount: (number) Counter for edits on this photo. First supported in version 2.0 of the Lightroom SDK.
New to version 2.0: The ISO8601 strings are generally more reliable than the Cocoa date stamp.
Return value
(any) The value of the specified metadata property as the appropriate data type, or nil if not applicable - photo:setPropertyForPlugin( plugin, fieldName, value )
-
Sets a plug-in-specific metadata value for this photo.
Must be called from within one of the
catalog:with___WriteAccessDogates (includingwithPrivateWriteAccessDo).First supported in version 2.0 of the Lightroom SDK.
Parameters
- 1. plugin
- (_PLUGIN object) The _PLUGIN object from your plug-in.
- 2. fieldName
- (string) The field name, as declared in an
LrMetadataProviderscript. - 3. value
- (string) The new value for this field. This must agree with data type specified for the field, if any.
- photo:setRawMetadata( key, value )
-
Sets metadata for this photo.
Must be called from within a
catalog:withWriteAccessDoorcatalog:withProlongedWriteAccessDogate.First supported in version 2.0 of the Lightroom SDK.
Parameters
- 1. key
- (string) The metadata item to set. The following keys are recognized:
- rating: (number) The user rating of the file (number of stars)
- label: (string) The name of assigned color label
- title: (string) The title of photo
- caption: (string) The caption for photo
- creator
- creatorJobTitle
- creatorAddress
- creatorCity
- creatorStateProvince
- creatorPostalCode
- creatorCountry
- creatorPhone
- creatorEmail
- creatorUrl
- headline
- iptcSubjectCode
- descriptionWriter
- iptcCategory
- iptcOtherCategories
- dateCreated: (string) The IPTC-formatted creation date (for example, "2005-09-20T15:10:55Z")
- intellectualGenre
- scene
- location
- city
- stateProvince
- country
- isoCountryCode
- jobIdentifier
- instructions
- provider
- source
- copyright
- rightsUsageTerms
- copyrightInfoUrl
- 2. value
- The value to set for this metadata item. See above list for acceptable value types. (String if not otherwise specified.)
- photo:withSettingsForPluginDo( pluginId, func )
-
Deprecated: Gets and sets plug-in-specific metadata for this photo. Use to wrap your function, which is passed a table of plug-in-specific settings. Your code can read or write values in this table of types Boolean, number, or string, and tables containing only those types. The modified table is stored as long as this photo is in the Lightroom catalog. You can eliminate these settings for a photo by deleting all keys.
Warning: This function is deprecated as of Lightroom 2.0 and will not be supported in Lightroom 3.0.
Example:
photo:withSettingsForPluginDo( 'com.adobe.lightroom.export.flickr', function( settings )
settings.photo_id = flickrPhotoId
end )If the called function returns the Boolean value
false, any changes made to the table are discarded.Must be called from within one of the
catalog:with___AccessDogates.First supported in version 1.3 of the Lightroom SDK.
Parameters
- 1. pluginId
- (string) The identifying name of the plug-in. This is the value of the Lightroom-defined property key
LR_exportServiceProvider. - 2. func
- (function) The function to execute.
Properties
- photo.catalog : (Read-Only)
-
(
LrCatalog) The catalog object that contains this photo.First supported in version 1.3 of the Lightroom SDK.
See also: LrCatalog - photo.countStackInFolderMembers : (Read-Only)
-
(number) The number of the members of the stack that this photo is in.
Must be called from within one of the
catalog:with___AccessDogates.First supported in version 2.0 of the Lightroom SDK.
- photo.countVirtualCopies : (Read-Only)
-
(number) The number of virtual copies of this photo. Zero if this photo is itself a virtual copy.
Must be called from within one of the
catalog:with___AccessDogates.First supported in version 2.0 of the Lightroom SDK.
- photo.isInStackInFolder : (Read-Only)
-
(Boolean) True if the photo is in a stack.
Must be called from within one of the
catalog:with___AccessDogates.First supported in version 2.0 of the Lightroom SDK.
- photo.isVirtualCopy : (Read-Only)
-
(Boolean) True if this photo is a virtual copy of another photo.
Must be called from within one of the
catalog:with___AccessDogates.First supported in version 2.0 of the Lightroom SDK.
- photo.masterPhoto : (Read-Only)
-
(
LrPhoto) The master photo from which this virtual copy is derived. If this photo is not a virtual copy, contains this photo.Must be called from within one of the
catalog:with___AccessDogates.First supported in version 2.0 of the Lightroom SDK.
- photo.path : (Read-Only)
-
(string) The current path to the photo file if available; otherwise, the last known path to the file.
Must be called from within one of the
catalog:with___AccessDogates.First supported in version 2.0 of the Lightroom SDK.
- photo.stackInFolderIsCollapsed : (Read-Only)
-
(Boolean) True if the stack containing this photo is collapsed.
Must be called from within one of the
catalog:with___AccessDogates.First supported in version 2.0 of the Lightroom SDK.
- photo.stackInFolderMembers : (Read-Only)
-
(array of
LrPhoto) All members of the stack that this photo is in.Must be called from within one of the
catalog:with___AccessDogates.First supported in version 2.0 of the Lightroom SDK.
- photo.stackPositionInFolder : (Read-Only)
-
(string) The position of this photo in the stack. The top of the stack is at position 1; other photos are numbered sequentially starting from 2.
Must be called from within one of the
catalog:with___AccessDogates.First supported in version 2.0 of the Lightroom SDK.
- photo.topOfStackInFolderContainingPhoto : (Read-Only)
-
(LrPhoto) The parent photo of the stack containing this photo.
Must be called from within one of the
catalog:with___AccessDogates.First supported in version 2.0 of the Lightroom SDK.
- photo.uuid : (Read-Only)
- (string) Persistent ID for this photo.
- photo.virtualCopies : (Read-Only)
-
(array of
LrPhoto) All virtual copies of this photo. Empty if this photo is itself a virtual copy.Must be called from within one of the
catalog:with___AccessDogates.First supported in version 2.0 of the Lightroom SDK.