Class LrPhoto

An object of this class represents a single photo or virtual copy in Lightroom's active catalog. Use the functions to access metadata stored with the image, or to associate your own data with a photo.

Objects of this type are returned by various functions of LrCatalog and LrExportSession.

Summary

photo:addKeyword( keyword )
Adds a keyword to this photo.
photo:applyDevelopPreset( preset, plugin )
Applies a develop preset to this photo.
Applies metadata presets to this photo.
Reports whether this photo is believed to be present on disk at this time.
photo:createDevelopSnapshot( snapshotName, updateInPlace )
Creates a develop snapshot of this photo.
Retrieves the photo collections that contain this photo.
Retrieves the published photo collections that contain this photo.
Retrieves the current develop settings for this photo.
Retrieves display-formatted metadata from this photo.
photo:getNameViaPreset( filenamePresetId, customString, sequenceNumber )
Creates a new name for the photo in a filename preset.
photo:getPropertyForPlugin( plugin, fieldId, optVersion, noThrow )
Retrieves plug-in-specific metadata for this photo, as declared in an LrMetadataProvider script.
Retrieves unformatted metadata from this photo.
photo:removeKeyword( keyword )
Removes a keyword from this photo.
photo:setPropertyForPlugin( plugin, fieldId, value, optVersion )
Sets a plug-in-specific metadata value for this photo.
photo:setRawMetadata( key, value )
Sets metadata for this photo.
Deprecated: This function was marked deprecated as of Lightroom 2.0 and is no longer supported as of Lightroom 3.0.
(LrCatalog) The catalog object that contains this photo.
Deprecated: (number) The number of the members of the stack that this photo is in.
Deprecated: (number) The number of virtual copies of this photo.
Deprecated: (Boolean) True if the photo is in a stack.
Deprecated: (Boolean) True if this photo is a virtual copy of another photo.
Deprecated: (LrPhoto) The master photo from which this virtual copy is derived.
Deprecated: (string) The current path to the photo file if available; otherwise, the last known path to the file.
Deprecated: (Boolean) True if the stack containing this photo is collapsed.
Deprecated: (array of LrPhoto) All members of the stack that this photo is in.
Deprecated: (string) The position of this photo in the stack.
Deprecated: (LrPhoto) The parent photo of the stack containing this photo.
Deprecated: (string) Persistent ID for this photo.
Deprecated: (array of LrPhoto) All virtual copies of this photo.

Functions

photo:addKeyword( keyword )
Adds a keyword to this photo.

Must be called from within a catalog:withWriteAccessDo or catalog:withProlongedWriteAccessDo gate.

This call can be used within the same catalog:with___WriteAccessDo call that created this keyword.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. keyword
(LrKeyword) The keyword object.
photo:applyDevelopPreset( preset, plugin )
Applies a develop preset to this photo.

Must be called from within a catalog:withWriteAccessDo or catalog:withProlongedWriteAccessDo gate.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. preset
(LrDevelopPreset) The preset object.
2. plugin
(optional, _PLUGIN) The plug-in object with which the preset is associated, if the preset was obtained using LrApplication:getDevelopPresetsForPlugin().

See also

LrDevelopPreset
photo:applyMetadataPreset( presetId )
Applies metadata presets to this photo.

Must be called from within a catalog:withWriteAccessDo or catalog:withProlongedWriteAccessDo gate.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. presetId
(string) The unique identifier of the metadata preset. See LrApplication.metadataPresets.
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.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 2.0 of the Lightroom SDK.

Return value

(Boolean) True if file is thought to exist at this time.
photo:createDevelopSnapshot( snapshotName, updateInPlace )
Creates a develop snapshot of this photo.

Must be called from within a catalog:withWriteAccessDo or catalog:withProlongedWriteAccessDo gate.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. snapshotName
(string) The name of the new snapshot.
2. updateInPlace
(Boolean) True to update the snapshot in place, if one already exists with this name. If false, take no action and return false.

Return value

(Boolean) True on success. False if a snapshot with this name already exists and was not updated.
photo:getContainedCollections()
Retrieves the photo collections that contain this photo. Note that only standard collections are listed by this function; any smart collections containing this photo will not be listed.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Return value

(table of LrCollection) The list of collection objects.

See also

LrCollection
photo:getContainedPublishedCollections()
Retrieves the published photo collections that contain this photo. Note that only standard published collections are listed by this function; any smart published collections containing this photo will not be listed.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Return value

(table of LrPublishedCollection) The list of collection objects.

See also

LrPublishedCollection
photo:getDevelopSettings()
Retrieves the current develop settings for this photo.

First supported in version 3.0 of the Lightroom SDK.

Must be called from within a task started using LrTasks.

WARNING:The develop settings APIs are considered experimental. You should not depend on the contents of the settings table remaining compatible in future versions of Lightroom. The definitive list is the one shown in the UI.

Return value

(table) Develop settings table. Contains the following members.
  • AutoBrightness: (boolean)
  • AutoContrast: (boolean)
  • AutoExposure: (boolean)
  • AutoShadows: (boolean)
  • BlueHue: (number)
  • BlueSaturation: (number)
  • Brightness: (number)
  • CameraProfile: (string)
  • ChromaticAberrationB: (number)
  • ChromaticAberrationR: (number)
  • Clarity: (number)
  • ColorNoiseReduction: (number)
  • ColorNoiseReductionDetail: (number)
  • Contrast: (number)
  • ConvertToGrayscale: (boolean)
  • CropAngle: (number)
  • CropBottom: (number)
  • CropLeft: (number)
  • CropRight: (number)
  • CropTop: (number)
  • Defringe: (number)
  • EnableCalibration: (boolean)
  • EnableColorAdjustments: (boolean)
  • EnableDetail: (boolean)
  • EnableEffects: (boolean)
  • EnableGradientBasedCorrections: (boolean)
  • EnableGrayscaleMix: (boolean)
  • EnableLensCorrections: (boolean)
  • EnablePaintBasedCorrections: (boolean)
  • EnableRedEye: (boolean)
  • EnableRetouch: (boolean)
  • EnableSplitToning: (boolean)
  • Exposure: (number)
  • FillLight: (number)
  • GrainAmount: (number)
  • GrainFrequency: (number)
  • GrainSize: (number)
  • GreenHue: (number)
  • GreenSaturation: (number)
  • HighlightRecovery: (number)
  • HueAdjustmentAqua: (number)
  • HueAdjustmentBlue: (number)
  • HueAdjustmentGreen: (number)
  • HueAdjustmentMagenha: (number)
  • HueAdjustmentOrange: (number)
  • HueAdjustmentPurple: (number)
  • HueAdjustmentRed: (number)
  • HueAdjustmentYellow: (number)
  • LuminanceAdjustmentAque: (number)
  • LuminanceAdjustmentBlue: (number)
  • LuminanceAdjustmentGreen: (number)
  • LuminanceAdjustmentMagenta: (number)
  • LuminanceAdjustmentOrange: (number)
  • LuminanceAdjustmentPurple: (number)
  • LuminanceAdjustmentRed: (number)
  • LuminanceAdjustmentYellow: (number)
  • LuminanceNoiseReductionContrast: (number)
  • LuminanceNoiseReductionDetail: (number)
  • LuminanceSmoothing: (number)
  • ParametricDarks: (number)
  • ParametricHighlightSplit: (number)
  • ParametricHighlights: (number)
  • Parametriclights: (number)
  • ParametricMidtoneSplit: (number)
  • ParametricShadowSplit: (number)
  • ParametricShadows: (number)
  • PostCropVignetteAmount: (number)
  • PostCropVignetteFeather: (number)
  • PostCropVignetteHighlightContrast: (number)
  • PostCropVignetteMidpoint: (number)
  • PostCropVignetteRoundness: (number)
  • PostCropVignetteStyle: (number)
  • ProcessVersion: (string)
  • RedEyeInfo: (table)
  • RedHue: (number)
  • RedSaturation: (number)
  • RetouchInfo: (table)
  • Saturation: (number)
  • SaturationAdjustmentAqua: (number)
  • SaturationAdjustmentBlue: (number)
  • SaturationAdjustmentGreen: (number)
  • SaturationAdjustmentMagenta: (number)
  • SaturationAdjustmentOrange: (number)
  • SaturationAdjustmentPurple: (number)
  • SaturationAdjustmentRed: (number)
  • SaturationAdjustmentYellow: (number)
  • ShadowTint: (number)
  • Shadows: (number)
  • SharpenDetail: (number)
  • SharpenEdgeMasking: (number)
  • SharpenRadius: (number)
  • Sharpness: (number)
  • SplitToningBalance: (number)
  • SplitToningHighlightHue: (number)
  • SplitToningHighlightSaturation: (number)
  • SplitToningShadowHue: (number)
  • SplitToningShadowSaturation: (number)
  • ToneCurve: (table)
  • ToneCurveName: (string)
  • Vibrance: (number)
  • VignetteAmount: (number)
  • VignetteMidpoint: (number)
  • WhiteBalance: (string)
  • Orientation: (string)
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.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates, but must be called from within a task started using LrTasks.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. key
(string) Which metadata item to retrieve, return an array of all available metadata fields as key/value pairs if nil. These valid keys return these values:
  • keywordTags: (string) The list of keywords as shown in the Keyword Tags panel (with Enter Keywords selected). This is the exact set of tags that were directly applied to the photo without any filtering for "Show on Export" flags, etc.
  • keywordTagsForExport: (string) The list of keywords as shown in the Keyword Tags panel (with Will Export selected). First supported as of Lightroom 2.0. This removes tags that were meant to be hidden via "Show on Export" and inserts all of the parents and ancestor tags (except when silenced via "Export Containing Keywords").
  • 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")
  • croppedDimensions: (string) The cropped 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) The 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: (string) The name of the person that created this image
  • creatorJobTitle: (string) The job title of the person that created this image
  • creatorAddress: (string) The address for the person that created this image
  • creatorCity: (string) The city for the person that created this image
  • creatorStateProvince: (string) The state or province for the person that created this image
  • creatorPostalCode: (string) The postal code for the person that created this image
  • creatorCountry: (string) The country for the person that created this image
  • creatorPhone: (string) The phone number for the person that created this image
  • creatorEmail: (string) The email address for the person that created this image
  • creatorUrl: (string) The web URL for the person that created this image
  • headline: (string) A brief, publishable synopsis or summary of the contents of this image
  • iptcSubjectCode: (string) Values from the IPTC Subject NewsCode Controlled Vocabulary (see: http://www.newscodes.org/)
  • descriptionWriter: (string) The name of the person who wrote, edited or corrected the description of the image
  • iptcCategory: (string) Deprecated field; included for transferring legacy metadata
  • iptcOtherCategories: (string) Deprecated field; included for transferring legacy metadata
  • dateCreated: (string) The IPTC-formatted creation date (for example, "2005-09-20T15:10:55Z")
  • intellectualGenre: (string) A term to describe the nature of the image in terms of its intellectual or journalistic characteristics, such as daybook, or feature (examples at: http://www.newscodes.org/)
  • scene: (string) Values from the IPTC Scene NewsCodes Controlled Vocabulary (see: http://www.newscodes.org/)
  • location: (string) Details about a location shown in this image
  • city: (string) The name of the city shown in this image
  • stateProvince: (string) The name of the state shown in this image
  • country: (string) The name of the country shown in this image
  • isoCountryCode: (string) The 2 or 3 letter ISO 3166 Country Code of the country shown in this image
  • jobIdentifier: (string) A number or identifier needed for workflow control or tracking
  • instructions: (string) Information about embargoes, or other restrictions not covered by the Rights Usage field
  • provider: (string) Name of person who should be credited when this image is published
  • source: (string) The original owner of the copyright of this image
  • copyright: (string) The copyright text for this image
  • rightsUsageTerms: (string) Instructions on how this image can legally be used
  • copyrightInfoUrl

The following items are first supported in version 3.0 of the Lightroom SDK.

  • personShown: (string) Name of a person shown in this image
  • locationCreated: (table) The location where the photo was taken. Each element in the return table is a table which is a structure named LocationDetails as defined in the IPTC Extension spec. Definition details can be found at http://www.iptc.org/std/photometadata/2008/specification/.
  • locationShown: (table) The location shown in this image. Each element in the return table is a table which is a structure named LocationDetails as defined in the IPTC Extension spec. Definition details can be found at http://www.iptc.org/std/photometadata/2008/specification/.
  • nameOfOrgShown: (string) Name of the organization or company featured in this image
  • codeOfOrgShown: (string) Code from a controlled vocabulary for identifying the organization or company featured in this image
  • event: (string) Names or describes the specific event at which the photo was taken
  • artworksShown: (table) A set of metadata about artwork or an object in the image. Each element in the return table is a table which is a structure named ArtworkOrObjectDetails as defined in the IPTC Extension spec. Definition details can be found at http://www.iptc.org/std/photometadata/2008/specification/.
  • additionalModelInfo: (string) Information about the ethnicity and other facets of model(s) in a model-released image
  • modelAge: (string) Age of human model(s) at the time this image was taken in a model released image
  • minorModelAge: (string) Age of the youngest model pictured in the image, at the time that the image was made
  • modelReleaseStatus: (string) Summarizes the availability and scope of model releases authorizing usage of the likenesses of persons appearing in the photo
  • modelReleaseID: (string) A PLUS-ID identifying each Model Release
  • imageSupplier: (table) Identifies the most recent supplier of this image, who is not necessarily its owner or creator. Each element in the return table is a table which is a structure named ImageSupplierDetail defined in PLUS. Definition details can be found at http://ns.useplus.org/LDF/ldf-XMPReference.
  • registryId: (table) Both a Registry Item Id and a Registry Organization Id to record any registration of this photo with a registry. Each element in the return table is a table which is a structure named RegistryEntryDetail as defined in the IPTC Extension spec. Definition details can be found at http://www.iptc.org/std/photometadata/2008/specification/.
  • maxAvailWidth: (number) The maximum available width in pixels of the original photo from which this photo has been derived by downsizing
  • maxAvailHeight: (number) The maximum available height in pixels of the original photo from which this photo has been derived by downsizing
  • sourceType: (string) The type of the source of this digital image, selected from a controlled vocabulary
  • imageCreator: (table) Creator or creators of the image. Each element in the return table is a table which is a structure named ImageCreatorDetail defined in PLUS. Definition details can be found at http://ns.useplus.org/LDF/ldf-XMPReference.
  • copyrightOwner: (table) Owner or owners of the copyright in the licensed image. Each element in the return table is a table which is a structure named CopyrightOwnerDetail defined in PLUS. Definition details can be found at http://ns.useplus.org/LDF/ldf-XMPReference.
  • licensor: (table) A person or company that should be contacted to obtain a license for using the photo, or who has licensed the photo. Each element in the return table is a table which is a structure named LicensorDetail defined in PLUS. Definition details can be found at http://ns.useplus.org/LDF/ldf-XMPReference.
  • propertyReleaseID: (string) A PLUS-ID identifying each Property Release
  • propertyReleaseStatus: (string) Summarizes the availability and scope of property releases authorizing usage of the likenesses of persons appearing in the image.
  • digImageGUID: (string) Globally unique identifier for the item, created and applied by the creator of the item at the time of its creation
  • plusVersion: (string) The version number of the PLUS standards in place at the time of the transaction

Return value

(string or table) The formatted-string value of the specified metadata property, or nil if not applicable. If no key is specified, returns a table of all available metadata fields as key/value pairs.
photo:getNameViaPreset( filenamePresetId, customString, sequenceNumber )
Creates a new name for the photo in a filename preset. See LrApplication.filenamePresets.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. filenamePresetId
(string) The unique identifier of the filename preset.
2. customString
(string) The name string.
3. sequenceNumber
(number) The sequence number to append to the name string.

Return value

(string) The new name.
photo:getPropertyForPlugin( plugin, fieldId, optVersion, noThrow )
Retrieves plug-in-specific metadata for this photo, as declared in an LrMetadataProvider script.

First supported in version 2.0 of the Lightroom SDK.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates, but must be called from within an asynchronous task started using LrTasks.

Parameters

1. plugin
(string or _PLUGIN) The plug-in object or unique identifying string for the plug-in that declares this field.
2. fieldId
(string) The metadata field's unique identifying key.
3. optVersion
(optional, number) The version number for the field (only valid in schema update handlers).
4. noThrow
(optional, Boolean) True to return an error (nil, error) instead of throwing an exception on error. (First supported in version 3.0 of the Lightroom SDK.)

Return values

  1. (any) The value of the specified metadata property as the appropriate data type, or nil if not applicable. If no key is specified, returns a table of all available metadata fields as key/value pairs.
  2. An error message on error, if noThrow is true.
photo:getRawMetadata( key )
Retrieves unformatted metadata from this photo.

First supported in version 1.3 of the Lightroom SDK.

As of version 2.0: ISO8601 strings are generally more reliable than the Cocoa date stamp.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates, but must be called from within a task started using LrTasks.

Parameters

1. key
(string) The metadata item to retrieve, of nil to get all available metadata fields. These valid keys return these values:
  • fileSize: (number) The size of the file in bytes
  • rating: (number) The user rating of the file (number of stars)
  • dimensions: (table) The original dimensions of file (for example, { width = 2304, height = 3072 } )
  • croppedDimensions: (table) The cropped dimensions of file (for example, { width = 2304, height = 3072 } )
  • 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)
  • 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)
  • countVirtualCopies: (number) The number of virtual copies of this photo. Zero if this photo is itself a virtual copy.
  • virtualCopies: (array of LrPhoto) All virtual copies of this photo.
  • masterPhoto: (LrPhoto) The master photo from which this virtual copy is derived.
  • isVirtualCopy: (Boolean) True if this photo is a virtual copy of another photo.
  • countStackInFolderMembers: (number) The number of the members of the stack that this photo is in.
  • stackInFolderMembers: (array of LrPhoto) All members of the stack that this photo is in.
  • isInStackInFolder: (Boolean) True if the photo is in a stack.
  • stackInFolderIsCollapsed: (Boolean) True if the stack containing this photo is collapsed.
  • stackPositionInFolder: (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.
  • topOfStackInFolderContainingPhoto: (LrPhoto) The parent photo of the stack containing this photo.
  • colorNameForLabel: (string) The color name corresponding to the color label associated with this photo.

The following items are first supported in version 2.0 of the Lightroom SDK.

  • fileFormat: (string) The format of the file. One of 'RAW', 'DNG', 'JPG', 'PSD', 'TIFF', or 'VIDEO'.
  • width: (number) The width of the original source photo in pixels.
  • height: (number) The height of the original source photo in pixels.
  • aspectRatio: (number) The aspect ratio of the photo (defined as width / height). (For example, a standard 35mm photo in landscape mode returns 1.5.).
  • isCropped: (Boolean) True if the photo has been cropped in Lightroom from its original dimensions.
  • dateTimeOriginalISO8601: (string) The date and time of capture (ISO 8601 string format).
  • dateTimeDigitizedISO8601: (string) The date and time of scanning (ISO 8601 string format).
  • dateTimeISO8601: (string) The adjusted date and time (ISO 8601 string format).
  • lastEditTime: (number) The date and time of the last edit to this photo (seconds since midnight GMT January 1, 2001).
  • editCount: (number) Counter for edits on this photo. (Warning: This is not an absolute counter. Consecutive changes within a few seconds are counted as a single edit.)

The following items are first supported in version 3.0 of the Lightroom SDK.

  • uuid: (string) Persistent ID for this photo
  • path: (string) The current path to the photo file if available; otherwise, the last known path to the file.
  • isVideo: (boolean) True if this file is a video.
  • durationInSeconds: (number) The duration in seconds if the file is a video.
  • keywords: (array of LrKeyword) The list of keyword objects for the photo.
  • customMetadata: (table) Custom metadata for this photo as shown in the Metadata panel. Each element in the return table is a table that describes one metadata field associated with a photo, with these entries:
    • id (string): A unique identifier for this field.
    • value (any): The value for this field, if any.
    • sourcePlugin (string): The unique identifier of the plug-in that defines the custom metadata.

Return value

(any) The value of the specified metadata property as the appropriate data type, or nil if not applicable. If no key is specified, returns a table of all available metadata fields as key/value pairs.
photo:removeKeyword( keyword )
Removes a keyword from this photo.

Must be called from within a catalog:withWriteAccessDo or catalog:withProlongedWriteAccessDo gate.

This call can be used within the same catalog:with___WriteAccessDo call that created this keyword.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. keyword
(LrKeyword) The keyword object.
photo:setPropertyForPlugin( plugin, fieldId, value, optVersion )
Sets a plug-in-specific metadata value for this photo.

Must be called from within one of the catalog:withWriteAccessDo gates (including withPrivateWriteAccessDo).

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. plugin
(_PLUGIN) The plug-in object.
2. fieldId
(string) The field name, as declared in an LrMetadataProvider script.
3. value
(string) The new value for this field. This must agree with data type specified for the field, if any.
4. optVersion
(optional, number) The version number for the field (only valid in schema update handlers). (First supported as of Lightroom 3.0.)
photo:setRawMetadata( key, value )
Sets metadata for this photo.

Must be called from within a catalog:withWriteAccessDo or catalog:withProlongedWriteAccessDo gate.

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 this photo.
  • caption: (string) The caption for this photo
  • copyName: (string) The name associated with this copy.
  • creator: (string) The name of the person that created this image.
  • creatorJobTitle: (string) The job title of the person that created this image.
  • creatorAddress: (string) The address for the person that created this image.
  • creatorCity: (string) The city for the person that created this image.
  • creatorStateProvince: (string) The state or province for the person that created this image.
  • creatorPostalCode: (string) The postal code for the person that created this image.
  • creatorCountry: (string) The country for the person that created this image.
  • creatorPhone: (string) The phone number for the person that created this image.
  • creatorEmail: (string) The email address for the person that created this image.
  • creatorUrl: (string) The web URL for the person that created this image.
  • headline: (string) A brief, publishable synopsis or summary of the contents of this image.
  • iptcSubjectCode: (string) Values from the IPTC Subject NewsCode Controlled Vocabulary (see: http://www.newscodes.org/).
  • descriptionWriter: (string) The name of the person who wrote, edited, or corrected the description of the image.
  • iptcCategory: (string) Deprecated field; included for transferring legacy metadata.
  • iptcOtherCategories: (string) Deprecated field; included for transferring legacy metadata
  • dateCreated: (string) The IPTC-formatted creation date (for example, "2005-09-20T15:10:55Z").
  • intellectualGenre: (string) A term to describe the nature of the image in terms of its intellectual or journalistic characteristics, such as daybook, or feature (examples at: http://www.newscodes.org/).
  • scene: (string) Values from the IPTC Scene NewsCodes Controlled Vocabulary (see: http://www.newscodes.org/).
  • location: (string) Details about a location shown in this image.
  • city: (string) The name of the city shown in this image.
  • stateProvince: (string) The name of the state shown in this image.
  • country: (string) The name of the country shown in this image.
  • isoCountryCode: (string) The 2 or 3 letter ISO 3166 Country Code of the country shown in this image.
  • jobIdentifier: (string) A number or identifier needed for workflow control or tracking.
  • instructions: (string) Information about embargoes, or other restrictions not covered by the Rights Usage field.
  • provider: (string) Name of person who should be credited when this image is published.
  • source: (string) The original owner of the copyright of this image.
  • copyright: (string) The copyright text for this image.
  • rightsUsageTerms: (string) Instructions on how this image can legally be used.
  • copyrightInfoUrl
  • colorNameForLabel: (string) The color name corresponding to the color label associated with this photo.

The following items are first supported in version 3.0 of the Lightroom SDK. For details of IPTC Extension definitions, see http://www.iptc.org/std/photometadata/2008/specification/". For details of PLUS definitions, see http://ns.useplus.org/LDF/ldf-XMPReference

  • personShown: (string) Name of a person shown in this image.
  • locationCreated: (table) The Locations shown in this image. Each element in the table is a table that is a structure named LocationDetails as defined in the IPTC Extension spec.
  • locationShown: (table) The locations where this photo was taken. Each element in the table is a table that is a structure named LocationDetails as defined in the IPTC Extension spec.
  • nameOfOrgShown: (string) Name of the organization or company featured in this image.
  • codeOfOrgShown: (string) Code from a controlled vocabulary for identifying the organization or company featured in this image.
  • event: (string) Names or describes the specific event at which this photo was taken.
  • artworksShown: (table) A set of metadata about artwork or an object in this image. Each element in the table is a table that is a structure named ArtworkOrObjectDetails, as defined in the IPTC Extension spec.
  • additionalModelInfo: (string) Information about the ethnicity and other facets of models in a model-released image.
  • modelAge: (string) Age of human models at the time this image was taken in a model-released image.
  • minorModelAge: (string) Age of the youngest model pictured in this image, at the time that the image was made.
  • modelReleaseStatus: (string) Summarizes the availability and scope of model releases authorizing usage of the likenesses of persons appearing in this image.
  • modelReleaseID: (string) A PLUS-ID identifying each Model Release.
  • imageSupplier: (table) Identifies the most recent supplier of this photo, who is not necessarily its owner or creator. Each element in the table is a table that is a structure named ImageSupplierDetail defined in PLUS.
  • registryId: (table) Both a Registry Item ID and a Registry Organization ID to record any registration of this item with a registry. Each element in the table is a table that is a structure named RegistryEntryDetail, as defined in the IPTC Extension spec.
  • maxAvailWidth: (number) The maximum available width in pixels of the original photo from which this photo has been derived by downsizing.
  • maxAvailHeight: (number) The maximum available height in pixels of the original photo from which this photo has been derived by downsizing.
  • sourceType: (string) The type of the source of this digital image, selected from a controlled vocabulary.
  • imageCreator: (table) Creator or creators of this image. Each element in the table is a table that is a structure named ImageCreatorDetail defined in PLUS.
  • copyrightOwner: (table) Owner or owners of the copyright in this licensed image. Each element in the table is a table that is a structure named CopyrightOwnerDetail defined in PLUS.
  • licensor: (table) A person or company that should be contacted to obtain a license for using this photo or who has licensed the photo. Each element in the table is a table that is a structure named LicensorDetail defined in PLUS.
  • propertyReleaseID: (string) A PLUS-ID identifying each property release.
  • propertyReleaseStatus: (string) Summarizes the availability and scope of property releases authorizing usage of the likenesses of persons appearing in this image.
2. value
(any) The value to set for this metadata item. See above list for acceptable value types. (String if not otherwise specified.)
photo:withSettingsForPluginDo()
Deprecated: This function was marked deprecated as of Lightroom 2.0 and is no longer supported as of Lightroom 3.0.

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)
Deprecated: (number) The number of the members of the stack that this photo is in.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates.

First supported in version 2.0 of the Lightroom SDK.

Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use photo:getRawMetadata( 'countStackInFolderMembers' ) instead.

photo.countVirtualCopies : (Read-Only)
Deprecated: (number) The number of virtual copies of this photo. Zero if this photo is itself a virtual copy.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates.

First supported in version 2.0 of the Lightroom SDK.

Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use photo:getRawMetadata( 'countVirtualCopies' ) instead.

photo.isInStackInFolder : (Read-Only)
Deprecated: (Boolean) True if the photo is in a stack.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates.

First supported in version 2.0 of the Lightroom SDK.

Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use photo:getRawMetadata( 'isInStackInFolder' ) instead.

photo.isVirtualCopy : (Read-Only)
Deprecated: (Boolean) True if this photo is a virtual copy of another photo.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates.

First supported in version 2.0 of the Lightroom SDK.

Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use photo:getRawMetadata( 'isVirtualCopy' ) instead.

photo.masterPhoto : (Read-Only)
Deprecated: (LrPhoto) The master photo from which this virtual copy is derived. If this photo is not a virtual copy, contains this photo.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates.

First supported in version 2.0 of the Lightroom SDK.

Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use photo:getRawMetadata( 'masterPhoto' ) instead.

photo.path : (Read-Only)
Deprecated: (string) The current path to the photo file if available; otherwise, the last known path to the file.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates.

First supported in version 2.0 of the Lightroom SDK.

Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use photo:getRawMetadata( 'path' ) instead.

photo.stackInFolderIsCollapsed : (Read-Only)
Deprecated: (Boolean) True if the stack containing this photo is collapsed.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates.

First supported in version 2.0 of the Lightroom SDK.

Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use photo:getRawMetadata( 'stackInFolderIsCollapsed' ) instead.

photo.stackInFolderMembers : (Read-Only)
Deprecated: (array of LrPhoto) All members of the stack that this photo is in.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates.

First supported in version 2.0 of the Lightroom SDK.

Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use photo:getRawMetadata( 'stackInFolderMembers' ) instead.

photo.stackPositionInFolder : (Read-Only)
Deprecated: (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.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates.

First supported in version 2.0 of the Lightroom SDK.

Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use photo:getRawMetadata( 'stackPositionInFolder' ) instead.

photo.topOfStackInFolderContainingPhoto : (Read-Only)
Deprecated: (LrPhoto) The parent photo of the stack containing this photo.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates.

First supported in version 2.0 of the Lightroom SDK.

Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use photo:getRawMetadata( 'topOfStackInFolderContainingPhoto' ) instead.

photo.uuid : (Read-Only)
Deprecated: (string) Persistent ID for this photo.

Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use photo:getRawMetadata( 'uuid' ) instead.

photo.virtualCopies : (Read-Only)
Deprecated: (array of LrPhoto) All virtual copies of this photo. Empty if this photo is itself a virtual copy.

As of Lightroom 3.0, no longer needs to be called from within one of the catalog:with___AccessDo gates.

First supported in version 2.0 of the Lightroom SDK.

Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use photo:getRawMetadata( 'virtualCopies' ) instead.