Space Urchin - Lightroom Plugin

Library filter to find metadata that has spaces in it (spaces in search term are considered part of the search term - not delimiters).

(triggered by selecting a special column in the metadata filter - without this column selected, lib filter functionality will not be effected).

Advanced users can use lua regex pattern matching too.

Ambitious users can define new presets for custom searches.

@v2.0 - Smarter collections (similar functionality as lib filter, except supports multiple search terms).

 

Featuring:

• Install and search. - Does not require special configuration, just select one of the lib filters supplied, or augment your own filters to add a (new) metadata column.
• 3 ways to use lib filter:
  1. Enter text in the library filter search box the same way you always have, except spaces will be considered part of the search term, instead of separators.
  2. Parsed mode: search text is parsed and interpreted according to a documented syntax.
  3. Search form - in case you are more comfortable using a form, or aren't connected to the internet where the syntax documentation is (this page).
• Supports lua regular expressions, in case plain text searches are not powerful enough for you.
• Customizable for special searching needs. You need to know a little lua, but then you can modify the value filtering function which is exposed as an "Advanced Setting".
• Smart collections can be augmented by defining a set of search specs that express matching metadata criteria.
• Keyword searches can include synonyms.

 

 

System Requirements

• Lightroom 3 or better.
• Windows or Mac (###1 not yet tested on Mac, but "should" be compatible).

 

Quick Links (intra-page)

Background Information
Screenshots
How it Works
How to Use
Text Search Box Syntax
FAQ (Frequently Answered Questions)
Revision History
Download

See the readme file after downloading for usage and other notes.

 

---

SpaceUrchin - Screenshots

 

Plugin Manager

Space Urchin mostly just works in the background.

 

File Menu (Plugin Extras)

Showing search form as alternative way to control lib-filtering;
And the new (@v2.0) smarter collections: Windows shortcut: Alt-F-S-"space".

 

Search Form

Menu-driven equivalent of using parsed mode of text search.
(searching from 2nd character to the end of the string)

 

Excerpt from Lib Filter dropdown menu

Showing the default "Space Urchin" filters - you can define more, or change these...

 

Metadata Filter after searching for keywords, inluding synonyms:

Filtering for photos that match the search criteria (or don't)

 

Progress Indicator (aka progress scope)

After smarter (dynamix'd) collection was updated, and a space-urchin lib-filter.
This progress indicator is displayed whenever space urchin library filters or smart(er) collections are selected.

 

Quit Lightroom prompt

What you see if you try to exit Lightroom while Space Urchin progress indicator is still displayed. (Its safe to 'Quit')

 

 

Background/Introduction

I was really getting tired of not being able to find metadata with spaces. Although none of my keywords have spaces (I noticed Lightroom's inability to handle spaces about a half decade ago), my titles and captions and other stuff have plenty of spaces. The trick was to make it efficient, so it was not necessary to invoke menu functions... Once I realized I can tap into the library filters with the SDK, Space Urchin was born.

 

Definitions (for the purposes of SpaceUrchin)

Library Filter	The bar in Lightroom with Text | Attribute | Metadata filtering options.
Text Search Box or 'Text Search Field'	the right most box in the 'Text' library filter for entering text to search for, which in the case of SpaceUrchin may be free-form or structured according to a syntax defined below.
Text Search Target	the dropdown with 'Any Searchable Field' at the top and 'Any Searchable Plugin Field' at the bottom.
Text Search Constraint	the dropdown with 'Contains' at the top and 'Ends With' at the bottom.
Progress Indicator	Upper left corner of Lightroom's main window. This is used in a somewhat non-traditional manner in SpaceUrchin - read on...
Blessed	A geek term that means "to distinquish in a special way".
Smarter Collection	A smart collection that's been "blessed" by having a file associated with it which includes a set of search specs. The smart collection also needs to have a criteria specified: the custom metadata item: Space Urchin Dynamix, contains, "Matching". This blessing occurs by selecting 'Smart(er) Collection' from the file menu.
Photo Source	Collection or folder.
Active Source	Selected collection or folder.

 

How it works

Smart Lib Filters

Space Urchin uses a custom metadata item called 'Space Urchin', as part of the lib filter. When that item is being used in the lib filter (a column in the 'Metadata' filter), that item is automatically updated based on the text in the search box.

Smarter Collections

When a smart collection is selected that has been "blessed" (smarter search criteria associated with it), the 'Space Urchin Dynamix' custom metadata item will be updated according to the specified search criteria.

 

Keys To Success

Lib Filters

Key points to understand, for best results:

1. Space Urchin updates match values only for visible photos (i.e. what is presently in the filmstrip).
2. All Space Urchin does is divides the visible photos up into "matching" and "non-matching" values. (depending on configurable filter-value function).
3. SpaceUrchin recomputes match/non-match values whenever something "pertinent" changes, or when user clicks the 'x' button of the progress indicator. (It will not recompute continually).
4. Lightroom will filter the view first independently of Space Urchin.

Examples demonstrating the implications of the above points:

#1 - The only way to make sure Lightroom's filtering does not filter any photos, and only SpaceUrchin does, is to specify a 'Text' filter where 'Any Searchable Field' 'Contains' 'a e i o u'. You can then explicitly specify the search type and name in the rest of the search box, e.g.

a e i o u | type=raw | name=path | text=" "

will search for all photos in the active source(s) whose source path has a space in it.

Without the a e i o u, Lightroom would prefilter all photos that don't have:

'type=raw', or '|', or 'name=path', or 'text="', or '"', i.e. almost all of them (hint: what Lightroom does is break the text in the search box into "terms" using the spaces as delimiter, then each term is searched for...).

#2 - One can take advantage of Lightroom's pre-filter to make SpaceUrchin an efficient search refiner:

If Lightroom's Text search is set to: 'Keywords', 'Contains Words' (careful of the "Big Mallard Ducks" bug in the 'Contains Words' constraint), then searching for:

Blue Moon

(with Space Urchin filter active) is very efficient, since Lightroom has already reduced the visible photos to those having 'Blue' or 'Moon', as "words" in the keyword. Photos having 'Blue Sky' and 'Full Moon' will also be displayed by Lightroom (thus the motivation for this plugin), but those won't match Space Urchin's criteria, so the only photos that will match are those having the term 'Blue Moon' - space and all.

Summary: the keys to success are:

1. Learning how to cast a big enough net to have all the photos you want subject to the matching/non-matching criteria of SpaceUrchin.
   1. Hint: use "Any Searchable Field" and/or "a e i o u".
2. Casting a small enough net to keep SpaceUrchin from considering photos that don't have a chance of matching anyway, and thus taking "forever" to update.
   1. Hint: Use tokens that you know must be present in the desired photos, like "Blue" and "Moon".
3. Learning to force recomputation over the desired photos, if the automatic update mechanism is not doing it (e.g. metadata in photo(s) have changed, but nothing else).
   1. Hint: Click "All (N Values)" in the SpaceUrchin column, or click the 'x' in the progress indicator.

Not sure what else to say - it works great once you get the hang of it!...

Smarter Collections

Much like the lib filters, except:

Photos subject to consideration are those in all active sources, and so the 'Space Urchin Dynamix' custom metadata item (that the Smarter Collection depends on for its extra smartness) is only updated when the active sources change. To force a re-update: same as for lib filters - click the 'x' in the progress indicator (or change active sources).

Note: Space Urchin will recognize changed search specs dynamically, so you can edit the specs and resave and they will be effective immediately (next update I mean, so click cancel 'x' if need be...).

 

How to Use SpaceUrchin

- Install (see readme file in downloaded zip file)
- Configure in plugin manager
- File menu functions
- The progress indicator
- Text search box syntax

 

Plugin Manager Configuration

See elare plugin framework for common settings.

Additional Settings and Controls

Background control	Leave this checked, otherwise SpaceUrchin won't work. The only reason to disable it is for troubleshooting, or if you really only want to use file-menu mode.
Background status	After plugin has "warmed up", it should say 'running'. If it doesn't, then consult the (verbose) log file for clues, and/or report problem to me. - try reloading the plugin and/or restarting Lightroom.

 

File Menu -> Plugin Extras

Most functionality comes from the menu items:

Search Form

All of Space Urchin's (lib filter) functionality initiated via a form, instead of typing in the lib filter's text search box.

 

 

The Progress Indicator

Space Urchin uses the progress indicator in a somewhat non-traditional fashion.

It's displayed whenever a space-urchin lib-filter or smart(er) collection is selected, and shows progress during updates.

Beware: If you try to cancel it, it will just re-update, again. i.e. canceling the progress indicator acts like a "refresh" (that's especially unconventional ;-) - try it! To really cancel it, just select a different smart collection and/or lib filter (ones that are not "special" to space-urchin).

 

 

Text Search Box Syntax

You can just type a search term in there that has spaces in it, like you are used to doing, except with a different interpretation of spaces (as part of search term instead of term separator), or use a name=value | name2=value2 | ... format:

name	value description
text	search text, interpreted as plain text (unless regex is true).
retext	search text, interpreted as lua regular expression (a shortcut instead of using 'regex').
regex	Set to 'true' to have text interpreted as lua regular expression (or just use 'retext').
start	where in the metadata to start looking for the search text.- first character is number 1, 2nd character is number 2, and so forth... Note: negative numbers are also acceptable: the last char is -1, the second to the last is -2, and so forth.
stop	specifies last character position to consider. Same constraints as start.
type	In case type is not to be inferred from the Text Search Target. Must also specify 'name'. Options: 'raw', 'keywords', or 'meta' ("formatted" metadata). See Lightroom SDK API documentation for details. (especially pertinent are LrPhoto page's getFormattedMetadata (for when type is 'meta'), and getRawMetadata (for when type is 'raw'). 'keywords' type relies on special handling of the information returned by photo:getRawMetadata( 'keywords' ). See LrKeyword I used to support a 'dev' type to search develop settings, but DevMeta already supports dev filters in a much better way.
name	Used in conjunction with 'type', to specify the metadata item to be searched.
syn	set to 'true' to search keyword synonyms too. Only applies when searching keywords.

Examples:

Text drop-down	text search box contents	description
Caption	brown hair	Search "Caption" metadata for 'brown hair'. Unlike Lightroom proper, SpaceUrchin will not match 'brown house' nor 'blonde hair'. *** This simple example captures the essence of SpaceUrchin, and why it was created.
Keywords	a e i o u | text=","	Search for all keywords that contain a comma (although keywords with commas can not be entered in Lightroom, they *can* be imported). Notes: Double-quotes when enclosing the search term, are removed before searching.
Keywords	a e i o u | retext=%d	Search for keywords that contain a digit.
Title	a e i o u | text="^ .*" | regex=true	Search for all titles that have a leading space. Regex syntax. Double-quotes are optional in this case.
Keywords	a e i o u | text=" "	Search for all keywords that have a space in them. Double-quotes are required.
Caption	a e i o u | retext = %c	Search for all captions having control character(s), including carriage return and/or linefeed. Spaces around %c are trimmed. If you don't want that, then surround with double-quotes.
Any Searchable Field	a e i o u | type=raw | name=path | retext="\[%l%d]"	Search for raw metadata, or more specifically for a file's path, for any subfolder beginning with a lower case letter or a digit. Note: 'Any Searchable Field' and 'a e i o u' are used to assure no files are eliminated by Lightroom before SpaceUrchin has a chance to search the path.
Keywords	a e i o u | type=meta | name=keywordTags | text=" > "	Search for all keywords that would be ambiguous without parental distinction.
Keywords	una | start=2 | stop="-2"	Search keywords for 'una' but omit the first and last characters from the search.

Note: 'Contains', 'Contains Words'... - constraints selected will affect Lightroom and the cross-section of photos subject to filtering. SpaceUrchin is not otherwise affected by its setting.

 

---

SpaceUrchin FAQ (Frequently Asked Questions)

(no particular order)

---

These FAQs come partly from users, and partly from my imagination. Please let me know if there are errors or omissions in this FAQ - thanks.

NOTE: The following Q&A's assume that the plugin is working as I expect... If, after your best effort, still "no go", please let me know.

---

Question: Why would I ever need or want such a thing as SpaceUrchin?

Answer: Lightroom treats spaces in library filter text search box as term separators, making it impossible to search for terms that have spaces in them. Space Urchin treats spaces as part of the search term.

---

Question: Space Urchin lib filter is not searching all the photos I want...

Answer: In order to enhance what is admittedly somewhat sluggish performance, SpaceUrchin will only search within photos presently showing. So you may have to click some other lib filter setting, or click another photo source, to recompute match values across all desired photos.

---

Question: Why does it say "Task in progress..." when I quit Lightroom?

Answer: Lightroom always warns if there is a progress indicator being displayed. Its safe to quit Lightroom, despite this "warning", but if it bugs you, just click 'None' on the lib filter bar before exiting Lightroom (or deselect smarter collection).

---

Question: What conditions result in recomputed match values? and how can I force an update?

Answer: When the search text changes, or the text target criteria, or the complement of photos being displayed. Stuff like that... Note: it is not recomputed over'n'over again if nothing changes, even if its the metadata in your photo(s) that's changing. If you want to force an update, the easiest way is just to "cancel" the progress indicator (click the 'x' ).

Note: Unlike smart(er) collections, lib filters are not updated if more than one photo is selected! - Explanation available upon request...

---

Question: How can I learn more about Lua regular expression syntax?

Answer: Read the lua documentation. Start here: www.lua.org.

---

Question: What if I have a '|' in my data?

Answer: Click 'Edit Advanced Settings' and change the delimiter.

---

Question: How do I change the search function behavior?

Answer: For lib-filters, click 'Edit Advanced Settings' and change the filterValue function. For smart(er) collections, select "Smart(er) Collection' from the file menu and edit the text file that will be loaded into your text editor - instructions are inside.

---

Question: How do I create new presets with new search functions, for lib-filters?

Answer:

1. Edit Metadata.lua, and add a metadata item (by example of an already existing one).
2. Enter the corresponding preset name in plugin manager then edit the config file and change the filterValue function.

---

Question: Any other hot tips I should know about?

Answer: Yes -

• Put "a e i o u" as the first item (or last item... - doesn't matter) when using parsed mode, so the search text will not exclude any items prematurely. (Or any set that is guaranteed to be in all non-blank fields - e.g. non-English languages).
• Conversely, put a limiting pre-filter term as first item, to cut down on the number of photos included - makes searching go faster.
• Smart(er) collections can be combined with folder selections (or other collections) to limit scope. Hint: ctrl/cmd-click additional photo sources.
• Cancel the progress indicator to force a re-update.
• Export a small test catalog so you can assign all kinds of whacky metadata to practice with.
• The progress indicator, when not actively processing an accepted search spec entry, provides real-time info if there's a typo in the search spec you are entering...

---

Question: What are the limitations of SpaceUrchin and what are your plans for the future?

Answer:

• Biggest limitation is performance. It takes a long time to update the filter if thousands of photos are being considered. I use a pre-filter term to cast a loose net, then SpaceUrchin to tighten it up.
• 2nd biggest limitation is handling of non-string metadata. The default filter function included with SpaceUrchin converts to string, then does match test. Although you can edit this function as an 'Advanced Setting', there's room for better support for date, boolean, and numeric values.
• Item lists in the search form are the actual "keys" obtained straight from the Lightroom SDK/API doc, and are only as accurate as that doc (and are not as friendly as they could be).
• Lightroom does not support direct plugin access to the set of photos subject to filtering (before filtering applied).
• Lightroom does not allow a plugin to handle text search field exclusively, thus SpaceUrchin is always refining a "hand-me-down" photo-set, i.e. Lightroom text filters are always active, so SpaceUrchin lib filters are always filtering a photoset that has already been pre-filtered by Lightroom.

---

SpaceUrchin Revision History

(reverse chronological order)

 

Version 2.0 released 2011-12-19

- Added the ability to define "smarter" collections.
- Added default lib filters (and a default smarter collection).

 

Version 1.0 released 2011-12-17

- Initial release.

---

 

Please (IDENTIFY THE PLUGIN) let me know what you think, and please (IDENTIFY THE PLUGIN) report bugs.

 

Download

acceptance of Download Terms & Conditions will be required

SpaceUrchin 2.0 - Latest & greatest - this is the one to download.

SpaceUrchin 1.0 - in case of problem with latest.