Annex D - Macro Command Parameters

Top  Previous 

 

IDimager supports so-called macro commands. Macro commands are variables that are replaced with their corresponding value when they are parsed. For example %FileName will be replaced with the actual file name of the image being processed. Macro commands can be used at several places in the application, for instance to rename files, to define a file name for the Downloader, in image captions, in frames, etc

 

Macro Commands can optionally be accompanied by parameters which allow you some control over what is returned. Parameters that accompany a macro command are places between accolade characters { }. Within the accolades you type the parameter with its value(s), separated by the equals sign. Some parameters allow multiple values and these can be separated by a comma. Multiple parameters can be separated by a semi colon.

 

An example would be: %FileName{left=5;UpperCase=Y} to return only the first 5 characters of the file name and return the result in upper case characters.

 

Parameters are not case sensitive.

 

This section describes the possible parameters.

 

Parameter

 

Values

Description

Example(s)

Left

n [Integer]

ellipsis [Constant]

This will return the left [n] characters of the parsed value

 

Use the optional "ellipsis" constant to add a trailing "..." leader when the result is truncated.

 

%FileName{left=5}

%ImageDescription{left=30,ellipsis}

Right

n [Integer]

ellipsis [Constant]

This will return the right [n] characters of the parsed value

 

Use the optional "ellipsis" constant to add a leading "..." leader when the result is truncated.

 

%xmp:dc:title{right=20}

%ImageDescription{right=60,ellipsis}

Mid

s [Integer]

n [Integer]

ellipsis [Constant]

This will return [n] characters of the parsed value, starting at position [s]

 

Use the optional "ellipsis" constant to add a trailing or leading "..." indicator when the result is truncated at the end or at the beginning.

 

%FileName{mid=4,10}

Delete

s [Integer]

n [Integer]

This will delete [n] characters of the parsed value, starting at position [s]

 

%FileName{delete=2,4}

Padd

n [Integer]

c [Char]

left [Constant]

This will return parsed value, padded to a specific length [n] using a specific character [c]. By default  the value is padded to the right. Optionally add the left constant to pad to the left instead of to the right.

 

%xmp:dc:title{padd=50,x,left}

%xmp:dc:title{padd=50, }

Uppercase

y [Constant]

This will return the value in uppercase characters

 

%FileName{uppercase=Y}

Lowercase

y [Constant]

This will return the value in lowercase characters

 

%FileName{lowercase=Y}

Reverse

y [Constant]

This will return the reversed string of the parsed value

 

%FileName{reverse=y}

Replace

sub [String]

replacement [String]

CaseSensitive [Constant]

FirstOnly [Constant]

 

This will replace a specific sub string [sub] with a replacement string [replacement].

 

By default all occurrences of [sub] will be replaced, regardless the case and regardless of the number of occurrences.

 

Optionally specify if the replacement should be case sensitive [CaseSensitive]

 

Optionally specify if only the first occurrence should be replaced [FirstOnly]  (default = all)

 

%xmp:dc:description{replace=Canon,Nikon}

%xmp:dc:description{replace=Canon,Nikon,CaseSensitive}

%xmp:dc:description{replace=Canon,Nikon,CaseSensitive,FirstOnly}

 

Trim

y [Constant]

This will return the parsed value without leading and trailing spaces

 

%FileName{trim=y}

Empty

s [String]

This will return the specified string [s] when the parsed value returns an empty value

 

%xmp:dc:description{empty=(no description)}

%xmp:dc:description{trim=y;empty=-none-}

Wrap

n [Integer]

This will wrap the parsed value to a specific number [n] of characters per line

 

%xmp:dc:description{wrap=30}

Trunc

n [Integer]

left [Constant]

This will break the parsed value at a specific length [n] and if the value is longer than [n] then the value is presented with a trailing or leading ... truncating identifier

 

Optionally you can use the [left] constant to define that the string should be truncated at the left instead of the default right

 

%FileName{trunc=15}

%FileName{trunc=15,left}

Word

n [Integer]

right [Constant]

separator [Constant]

This will return the [n]'th word of the parsed value.

 

You can specify the constant [right] to return the [n]'th word, starting from the right instead of from the left

 

By default the space character is used as the separator to tokenize the parsed value to words. Optionally specify a different [separator] as the third parameter.

 

%exif:Model{word=2}

%exif:Model(word=3,right}

%FileDirectoryName(word=1,right,\}

DateFormat

format [String]

Return a date string in a different format, based on date formatting settings. The input date string should either be an ISO Date String (yyyy-mm-ddThh:nn:ss+zz:zz) or in an Exif date format (yyyy:mm:dd hh:nn:ss) or in the format that is configured in Windows.

 

The format is a Delphi date formatting string. Date-Time Format Strings specify the formatting of date-time values when they are converted to strings.

 

Also see: http://www.delphibasics.co.uk/RTL.asp?Name=FormatDateTime

 

Here's a sample to extract the year and month part of the photo date of an image:

%ImagePhotoDate{dateformat=yyyy-mm}

 

 

 

 

Format

format [String]

Return a number string in a different format, based on number formatting settings.

The input number string should either be an ISO Number String (+number.fraction) or in the format that is configured in Windows.

 

The format is a Delphi number formatting string.

Format specifiers have the following form:

 

"%" [index ":"] ["-"] [width] ["." prec] type

 

A format specifier begins with a % character. After the % come the following, in this order:

 

An optional argument zero-offset index specifier (that is, the first item has index 0), [index ":"]

An optional left justification indicator, ["-"]

An optional width specifier, [width]

An optional precision specifier, ["." prec]

The conversion type character, type

 

Also see: http://www.delphibasics.co.uk/RTL.asp?Name=Format

 

This will list the Aperture  value with a precision of 5 decimals

%exif:ApertureValue{mid=2,100;format=%8.5f}

 

 

Some types of macro commands allow additional parameters which only apply to that kind.

 

%XMP Specific Parameters

 

These parameters only apply to XMP macro commands (starting with %xmp).

 

Parameter

 

Values

Description

Example(s)

Qualifier

s [String]

This parameter only applies to XMP properties of the Alt-type (multi language properties).

 

You can pass the country code as a [s].

 

%xmp:dc:description{qualifier=nl-nl}

 

This will return the Dutch language qualifier for this property

Element

n [Integer]

This parameter only applies to XMP properties of the Bag, and Sequence types (list/array types).

 

This will return the [n]'th element of the list/array

 

%xmp:dc:creator{element=3}

 

This will return the 3rd element of the dc:creator property

 

%ImageNumber Specific Parameters

 

These parameters only apply to the %ImageNumber macro command. This macro command can be used to generate  unique numbers;for example for file naming

 

Parameter

 

Values

Description

Example(s)

Offset

n [Integer]

Use the Offset to specify the starting number for the sequence

 

Note: the first pass will increase the offset, so specify 0 if you want to start at the first number available.

 

If unspecified then 0 is used as the offset

 

%FileName %ImageNumber{offset=999}.%FileExtension

 

test 1000.jpg

test 1001.jpg

test 1002.jpg

 

Increment

n [Integer]

Specify the number that you want to use to increment the sequence with.

 

If unspecified then 1 is used as the increment value

 

%FileName %ImageNumber{increment=2}.%FileExtension

 

test 2.jpg

test 4.jpg

test 6.jpg

 

Length

n [Integer]

Specify the number length that should be used for the sequence number

 

For numbers smaller than the specified length it will be padded at the front with zeros

 

%FileName %ImageNumber{length=3}.%FileExtension

 

test 001.jpg

test 002.jpg

test 003.jpg

 

 

Continuous


Use this parameter if you want to use a continuous number which is persistent between invocations.

 

In other words; IDimager will continue with the last used number

 

%FileName %ImageNumber{increment=2;continuous;length=3}.%FileExtension

 

if the last number was 3 then it will continue at the next number

 

test 004.jpg

test 006.jpg

test 008.jpg

 

Reset

s [String]

Use this parameter if you want the sequence to restart at a certain point

 

Possible values are:

NEVER (never reset; = default)

DATE (reset when the photo date of the image changes)

NUMBER (reset when the sequence exceeds a specific number)

PASSES (reset after a specific number of passes)

To reset the counter after 10 passes use something like:

 

%FileName %ImageNumber{offset=0;increment=1;reset=passes,10}.%FileExtension

 

 

To reset the counter after the number exceeds 9999, use something like:

 

%FileName %ImageNumber{offset=0;increment=1;reset=number,9999;length=4}.%FileExtension

 

 

%CatalogLabelList Specific Parameters

 

These parameters only apply to the %CatalogLabelList macro command. This macro command returns a list of every assigned catalog label for the image that this macro is used for.

 

Parameter

 

Values

Description

Example(s)

Separator

s [String]

Use the separator to use a different separator in between each label in the list. By default the elements are separated with a command+space

 

Note; you can not use the semi-colon as a separator because IDimager reserves the semi color as the separator for macro parameters.

 

%CatalogLabelList{separator=#}

Label 1#Label 2#Label 3

 

%CatalogLabelList{separator= | }

Label 1 | Label 2 | Label 3

Sort

s [String]

By default the list will be sorted by the label name. With this parameter you can gain some control over the sort order of the elements.

 

Valid options are:

Name -> sort by the label name

Path -> sort by the full path

GEO -> sort by the location on the globe map

 

%CatalogLabelList{sort=Path}

 

 

FullPath

s [String]

When this parameter is specified then IDimager will return the full qualified path to each label. Optionally specify the separator to be used as the path separator (default path separator = ::)

 

%CatalogLabelList{FullPath}

Returns: People::Family::Hert

 

%CatalogLabelList{FullPath=.}

Returns: People.Family.Hert

Referred


You can combine this parameter with FullPath. If FullPath is not used then this parameter is ignored.

When using referred FullPath then the hierarchical path to the catalog label will be listed after the label name instead of in front of the label name.

 

%CatalogLabelList{FullPath;Refered}

Returns: Hert (People::Family)