IMatch Documentation Global

Methods

init()

Call this to initialize the camera database.

Returns:

Promise

_load()

Load cached data from the local storage.

Returns:

Promise

_store()

Store the cached data.

reset()

Resets the camera database by clearing all locally cached data.
The class will request camera info again from the server on
future calls (rebuilding the cache on-demand).

getCameraInfo(make, model) → {Object}

Returns information about the given make/model.
NOTE: If the returned oject has the pending member set to true, the camera is in the database
but not yet updated with proper values. The crop factor will always be 1 in that case.

Parameters:

Name	Type	Description
`make`	String	The nake (from {File.MD.make})
`model`	String	The model (from {File.MD.model})

Returns:

The result member of the object can be one of
'ok' : The camera was found. The cropFactor is in the cropFactor member.
'' : The camera has not been looked up yet. Use lookupCameraInfo().

Type: Object

lookupCameraInfo(make, model) → {Promise}

Performs a lookup for the camera model in the camera database.

Parameters:

Name	Type	Description
`make`	*	Camera make
`model`	*	Camera model

Returns:

It is always resolved with the session state. The status member is either 'ok' (lookup completed) or 'pending' or unknown' for unknown mnodel.

Type: Promise

hasPending()

Returns:

true if there is at least one pending camera.

getPendingCameras()

Returns an array with cameras which are marked as pending.

onScopeChanged(cause)

This method is called when IMatch informs the File Window App about the change in the scope (model).
Such changes can be caused by many things, e.g. the user clicking on another folder, the user using the search bar or filter panel, changing the sort order etc.

Parameters:

Name	Type	Description
`cause`	String	The reason for the scope change.

onSortOrderChanged(reverse)

This methid is caled when the sort order changes between asc and desc. The user triggers this via the File Window toolbar.

Parameters:

Name	Type	Description
`reverse`	Boolean	The current state of the Asc/Desc sort order option. True when the sort order is reversed (Z..A).

onSortProfileChanged(profile)

The user selected a different sort profile in the File Window toolbar.
This also causes an IMatchFileWindow.onScopeChanged event.

Parameters:

Name	Type	Description
`profile`	String	The name of the currently selected sort profile.

onZoomChanged(zoom)

The user changed the zoom level of the File Window.

Parameters:

Name	Type	Description
`zoom`	Number	The new zoom level. The range for this number is by default 0-20, but it can be changed via the app.json of your File Window App.

onPauseThresholdChanged(threshold)

The user picked a new auto-pause theshold.

Parameters:

Name	Type	Description
`threshold`	*	The new threshold.

onActiveStateChanged(active)

The file window was actived or deactivated. When the user switches to another View or opens a result window, the current file window is deactivated.

Parameters:

Name	Type	Description
`active`	Boolean

onMoveFocus(next, selectAndFocus, keepSelection, ensureVisible)

IMatch has requested that the file window moves the focus to the previous or next file.
This is mostly used by the Quick Preview Panel, when the user navigates using the flaps.

Parameters:

Name	Type	Description
`next`	*	True to move to the next file, false to move to the previous file.
`selectAndFocus`	*	The new file should be focused and selected
`keepSelection`	*	False if the change should remove the current selection
`ensureVisible`	*	The newly selected file should be made visible.

onSearchRunning()

The user started a search via the File Window Search Bar.

onSearchCompleted(success)

The search has completed or was aborted by some reason.
IMatch applies the search result to the file window and causes the scope to change. Files no longer visible get the flag FileStates.esHiddenSearch.
This also causes an IMatchFileWindow.onScopeChanged event.

Parameters:

Name	Type	Description
`success`	*	True if the search has been successful.

onFilterRunning()

The Filter Panel is performing a query.

onFilterCanceled()

The current Filter Panel query was canceled.
This may cause an IMatchFileWindow.onScopeChanged event.

onFilterCompleted()

The Filter Panel has complete its query.
This may causes an IMatchFileWindow.onScopeChanged event.

enumerateRunningApps() → {Promise}

Lists all currently running File Window Apps.
This can be used to find out the instance id of a specific app, e.g., to connect to it from an external web browser.

Returns:

Type: Promise

getState() → {Promise}

Queries the current state of the File Window associated with this instance.

Returns:

Type: Promise

loadModel(params) → {Promise}

Loads the model of the File Window associated with this instance.
The model contains 1 to n groups, each group containing the file ids in that group plus other information.
Groups may be nested to any depth. The hierarhcy mode of the file window controls how the model is created from the current scope.

Parameters:

Name	Type	Description
`params`	Object	An object with additional parameters. You can specify the same parameters that can be used with the `/files` endpoint.

Returns:

Type: Promise

Example

let fw = new IMatchFileWindow(instance);
fw.loadModel({
  fields: 'id,namene,format,datetime,rating,label,labelcolor',
 tagdesc: 'description',
 tagtitle: 'title',
 tagkeywords: 'hierarchicalkeywords'
}).then(response => {
 // ...
});

setSelection(params)

This method changes the selection of the model maintained by the File Window.

Parameters:

Name	Type	Description
`params`	Object
`parameters.op`	String	How to apply the selection. Supported are 'set' to replace the selection and 'add' to add to the selection.
`parameters.id`	String	List of file ids. Standard IMWS syntax.

setFocus(id)

This selection changes the focused file in the model maintained by the File Window.

Parameters:

Name	Type	Description
`id`	Number	The id of the file to focus, or null to remove the focus

getImageUrl(id, size [, useDefault])

Parameters:

Name	Type	Argument	Default	Description
`id`	Number			The id of the file
`size`	String			The size of the image. See `/files` endpoint for details.
`useDefault`	Boolean	<optional>	true	If this is true and there is no image available for the file, a default image/icon is returned.

init( [forceLocale]) → {Promise}

Initialize this class. This must be called first.
If a global moment exists, it's locate will be set to the same locale as this class is using.

Parameters:

Name	Type	Argument	Default	Description
`forceLocale`	String	<optional>	false	By default, this class retrives the appLocale from IMatch. You can override this by specifying a locale with this parameter.

Returns:

If the promise is resolved, the locale data has been loaded and initialized() returns true.

Type: Promise

initialized() → {Boolean}

Check if this has been properly initialited by a call to init()

Returns:

True if this has been initialized.

Type: Boolean

locale() → {String}

Get the locale used by this.
NOTE: This is filled always, but may change after init() has been called.

Returns:

The locale identifier to use for all locale-specific operations.

Type: String

formatInt( [useGrouping], n)

Format an integer value.

Parameters:

Name	Type	Argument	Default	Description
`useGrouping`	Boolean	<optional>	true	Use thousands groupings?
`n`	Number			The number to format.

formatFloat(n [, useGrouping])

Format a floating point value.

Parameters:

Name	Type	Argument	Default	Description
`n`	*			The number to format.
`useGrouping`	Boolean	<optional>	true	Use thousands groupings?

formatCurrency(n [, currency] [, displayFormat])

Format a currency value.
Based on https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString

Parameters:

Name	Type	Argument	Default	Description
`n`	Number			The number to format.
`currency`	String	<optional>	'USD'	The currency to use: {USD,EUR,...}
`displayFormat`	String	<optional>	'symbol'	The currency format to use: {'code' (EUR), 'symbol' ($),'name' (Euro)}

formatPercent(n) → {String}

Format a percentage value.

Parameters:

Name	Type	Description
`n`	Number	The percentage to format (0.5 = 50%).

Returns:

Type: String

formatUnit(n [, unit] [, displayFormat]) → {String}

Format a unit like meter or litre.
Based on https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString

Parameters:

Name	Type	Argument	Default	Description
`n`	Number			The number to format
`unit`	String	<optional>	'm'	The unit to use: {'liter','kilogram','kilometer','meter','bit','byte',...}
`displayFormat`	String	<optional>	'short'	The type of unit formatting: {'short','long','narrow}

Returns:

Type: String

formatDateTime(isoDate, format)

Format a date in the local date and time format

Parameters:

Name	Type	Description
`isoDate`	String	The date to format. Must be in YYYY-MM-DD HH:MM:SS format
`format`	String	How to format the timestamp: 'LT', 'LTS', ... See https://momentjs.com/docs/#/displaying/

compareString(a, b)

Compares two strings using the current locale.

Parameters:

Name	Type	Description
`a`	String	string to compare
`b`	String	string to compare

load(xmlData [, simulateTimestamps]) → {Boolean}

Load a track log file from memory.

Parameters:

Name	Type	Argument	Default	Description
`xmlData`	String			The XML formatted GPX data.
`simulateTimestamps`	Boolean	<optional>	false	If this is true, a fixed date and time is used for points without a element. This is for testing purposes.

Returns:

If this method returns false, check the IMatchTrackLog#error property for more info.

Type: Boolean

tracks() → {Array}

This function returns the standardized points extracted from the file.
The returned array may have one or more sub-arrays, if multiple tracks
have been recored in the file.

Returns:

Type: Array

error()

Properties:

Name	Type	Description
`error`	String	The last error message.

authenticate(email, key, service) → {Promise}

This method authenticates the specified user for the specified service and retrieves a serviceToken from the host.
This serviceToken is used to authenticate the user when calling the APIs for that service.

NOTE: Usually you have to call this before calling any of the other service endpoints.

The only exception are endpoints which don't require authentication.

Parameters:

Name	Type	Description
`email`	String	The user name or email address.
`key`	String	Passowrd or license key.
`service`	String	The service to authenticate for.

Returns:

The promise is fulfilled with the service token on success, else rejected.

Type: Promise

Example

let ptcs = new PTCServices();
ptcs.authenticate('email','licenekey','service name').then(response => {
    // This token can now be used to access 'service name' API endpoints.
    myToken = response.serviceToken;
});

quotaInfo(serviceToken, serviceKey)

Queries the service quota info for the specified service token.
To get the service token call authenticate before as needed.

Parameters:

Name	Type	Description
`serviceToken`	String	The service quota to query.
`serviceKey`	String	The optional service key. If no key is provided, information about all services for the user is returned.

Returns:

Promise The response contains a JSON object with information about the service quoty (credits).

Example

{ 
 "service": "nnn",
  "used": 111,
  "remaining": 111,
  "total": 222,
  "type": 10,
  "typeName": "monthly",
  "periodStart": "2018-05-16 00:00:00",
  "nextReset": "2018-06-16 00:00:00"
}

translate(langFrom, langTo, text, serviceToken [, service]) → {Promise}

Uses machine translation to translate the given text.
The result format is the original format of the specified service.

Parameters:

Name	Type	Argument	Default	Description
`langFrom`	String			source language id, e.g. `en`.
`langTo`	String			target language id, e.g. `de`.
`text`	String			The text to translate. Note: For Azure (service MSAZTT) the following limits apply: Maximum 5,000 characters, including spaces.
`serviceToken`	String			the serviceToken retrieved with the authenticate method.
`service`	String	<optional>	'MSAZTT'	the name of the translation service to use. Must be the same used to get serviceToken.

Returns:

Will be fulfilled when the translation call is successful.
The response is a JSON wrapper object.
The result string contains the translated text.
The serviceData object contains the native data as returned by the translation service.
The ptcsData object contains quota and other technical data from the photools.com service.

Type: Promise

Example

let s = new PTCServices();

s.translate('en', 'de', 'The quick brown fox jumps over the lazy dog.', 'YOUR TOKEN').then(response => {
    console.log(response.serviceData[0].translations[0].text);
});

translateArray(langFrom, langTo, textArray, serviceToken [, service] [, progressCallback]) → {Promise}

Uses machine translation to translate the given text.
The result format is the original format of the specified service.

Parameters:

Name	Type	Argument	Default	Description
`langFrom`	String			source languages id, e.g. `en`.
`langTo`	String			target language id, e.g. `de`.
`textArray`	Array.<String>			An array of strings to translate. EMPTY STRINGS are not supported!
`serviceToken`	String			the serviceToken retrieved with the authenticate method.
`service`	String	<optional>	'MSAZTT'	the name of the translation service to use. Must be the same used to get serviceToken.
`progressCallback`	callback	<optional>		This callback is called frequently during the translation. If it returns false, the translation is aborted Note: For Azure (service MSAZTT) the following limits apply: Maximum 5,000 characters query.

Returns:

Will be fulfilled when the translation call is successful.
The response is a JSON array of objects. Depending on the service used and the number of array elements on input,
the result may contain one or more array elements. Each element is an object consisting of:
The result object contains key:value pairs with the original keys and translated text.
This is what you will use for typical scenarios.
The serviceData object contains the native data as returned by the translation service.
The ptcsData object contains quota and other technical data from the photools.com service.

Type: Promise

Example

const TEXTARRAY = {
  'key1' : 'First sentence to translate.',
  'key2' : 'The quick brown fox jumps over the lazy dog.',
  'key3' : 'Start Button'
};

let s = new PTCServices();

s.translateArray('en', 'de', TEXTARRAY, 'YOUR TOKEN').then(response => {
  // Contains 1 to many elements, depending on the number of elements in the input array
  // and if and where the service had to split the array.
  for (let r of response) {
     for (let t of r.result) {
        console.log(t.translations[0].text);
     }
  }
});

translateListLanguages(serviceToken [, service]) → {Promise}

This function retrieves a list of all languages supported by the specified translation service.
The result format is standardized between supported services.
The method returns a dictionary with the two-letter lang-id as the key. Each object has the name of the language in English,
plus the nativeName in the native language.

Parameters:

Name	Type	Argument	Default	Description
`serviceToken`	String			the serviceToken retrieved with the authenticate method.
`service`	String	<optional>	'MSAZTT'	the name of the translation service to use. Must be the same used to get serviceToken.

Returns:

Will be fulfilled when the translation call is successful. Returns the native response from the service used.

Type: Promise

Example

let s = new PTCServices();
     ptcs.translateListLanguages(serviceToken,service).then(response => {
        $('#data').text(JSON.stringify(response,null,2));
      },error => {
        $('#data').text(JSON.stringify(error,null,2));
      });

newsFeed( [productId] [, limit])

This method retrieves the current photools.com newsfeed. It consists of messages
directly from photools.com and also the recent limit messages from the photools.community.

Parameters:

Name	Type	Argument	Default	Description
`productId`	*	<optional>	null	If you want to query data for a specific product, specify the product id in this parameter.
`limit`	*	<optional>	20	The number of recent community posts to return.

Example

ptcs.newsFeed(productId,20).then(response => {
   console.log(JSON.stringify(response,null,2));
},error => {
  console.log(JSON.stringify(error,null,2));
});

camdbInfo() → {Promise}

Retrieves information about the photools.com camera database.

Returns:

If the promise is fulfilled, it contains information about the camera database.

Type: Promise

Example

let ptcs = new PTCServices();

ptcs.camdbInfo().then(response => {
    console.log(JSON.stringify(response,null,2));
});

camdbDownload() → {Promise}

Downloads the camera database in JSON format.

Returns:

Type: Promise

Example

let ptcs = new PTCServices();
ptcs.camdbDownload().then(response => {
    console.log(JSON.stringify(response,null,2));
});

camdbGet(make, model)

Retrieves information for the camera with the specified make and model name. The make/model parameters are not case-sensitive.

NOTE: The content of these parameters must exaclty match the contents found in the EXIF make and model tags.

Parameters:

Name	Type	Description
`make`	String	The contents of the EXIF make tag of the camera for which to retrieve information.
`model`	String	The contents of the EXIF model tag.

Example

let ptcs = new PTCServices();

ptcs.camdbGet('NIKON CORPORATION', 'NIKON D300').then(response => {
    console.log(JSON.stringify(response,null,2));
},error => {
    // Camera does not exist in the camera database.
    console.log(JSON.stringify(error,null,2));
});