Dave Mitchell's DigitalMicrograph™ Scripting Website

In general, any script involving more than a few lines of code should be written as one or more functions. Think of a function like a vending machine. You put in certain inputs - an amount of cash, some keypad presses and a few judicious thumps. In return you get specifc outputs such as a chocolate bar (if you are lucky). You do not care how the vending machine works. All you need to know is what inputs are required and what outputs it can return to you.

Functions should have no external dependencies ie they should use no variables other than those passed into them. This makes operation of the function completely transparent, and allows it to be copy-and-pasted directly into new scripts. Provided the right inputs and outputs are used, the function will work seamlessly in any script. All variables used within the function are local to it, so there are no conflicts with other parts of your script. You can use the same variable name inside and outside a function. What happens inside a function is completely invisible to the rest of the script. The only exception to this is variables which are passed by reference. This is useful when more than one variable needs to be returned by a function. The reference variables are passed into the function, the values are modifed and are then available to the rest of the script. A detailed description of how to write and use functions can be found in the Scripting Digital Micrograph tutorial.

A good way to develop scripts is to break the script operations down into specfic tasks - continually sub-dividing tasks into simpler and simpler blocks - the simpler the better. For example you may write a function for finding and closing all images a particular scripts creates. This function may be used at several points in your script, such as when initialising the display, when resetting the script (especially if it is a dialog) and perhaps when shutting down a script. At each use the function can be called by a single line, as opposed to cloning the relevant code at each point of use. This avoids code bloat and makes the operation of the script easy to follow and simple to debug. Most importantly, you will be able to re-use functions in your scripts greatly speeding up development - think of them as prefabricated parts of a building. Maximum flexibility is achieved by keeping functions short and simple and avoiding external dependencies. It is better to break down a task into functions A, B and C, and then call them in that order, rather than creating single large function for all three operations.

The functions listed here have some additional code in the main section of the script which provides the function with test data, then calls the function to illustrate how it works. Functions can be copy-and-pasted directly into users' own scripts. Alternatively, they may be installed into DigitalMicrograph as Library files - see theTutorial on Installing Scripts for information on this. In general, it is better to include any functions you call in your scripts, that way they are more portable. A script which calls a function installed as a Library file, will only work on instances of DigitalMicrograph where the Library file is present.

Curves/Interpolation

• Compute 2D Polynomial Fit: This function computes a 2D polynomial fit mapping the relationship between two 2D arrays of points.
• Create 2D Gaussian: Creates a 2D Gaussian blob image for fitting to a diffracton spot or atomic column.
• Fast Cubic Spline: Parameterised (fast) cubic spline calculates the series of constatnts A, B, C and D in the equation y=A + Bx + cx^2 + dx^3. The array of constants is calculated in a single slow step by the function calculatesplineconstants(). The array of constants is then passed to a second function (fastcubicspline()) which uses them in a loop for quick calculation a series of interpolated values.
• Find Centre of Gravity:Function to find the centre of gravity of the passed in image.
• Find Coordinates of a Point along a Straight Line: Finds the coordinates of a point a given distance along a line.
• Fit an n Order 2D Polynomial:This function will compute the linear least squares fit of a 2D polynomial to a surface described by the intensity values in an image.
• Gaussian Fit: This function will fit a Gaussian to a peak (identified by having a region of interest drawn across it). The fitted peak and the various peak parameters are returned.
• Interpolate Peak Inflection Point: A function which computes the maximum of a smooth curve drawn through three points. Use this for obtaining sub-pixel precision in locating peak maxima.
• Linear Regression: Function to perform a linear regression on an array of data passed in to it. Calculates the constants a and b in y=a+bx, the 95% confidence interval and the R parame
• Linear Regression using Matrices: A function to carry out linear regression of a 1D plot, using matrices.
• Linear Regression of a 2D Plane: Function to carry out a linear regression to calculate the best 2D plane fit to an image.
• Natural and Constrained Cubic Spline: Function to calculate the natural cubic spline of a data set. This draws a smooth curve through a series of data points. There is also a constrainedcubicspline() function which has clamped ends. This avoids the oscillations that can sometimes appear at the end of spline fitted curves or where data bunches. However, the constrainedcubicspline() function does this at the expense of smoothness.
• Polynomial Fit: Fits an nth order polynomial to a 1D dataset.
• Replace Outliers with Mean: Function to replace outliers in a 1D data set with either the rolling mean or zero.

 

Data Conversion

• Convert a Hexadecimal String into a Number: A function which will convert the passed in string from hexadecimal and return its equivalent value as a decimal number.
• Convert a Multi-image Imagedocument into a Single Image: This function takes an imagedocument containing multiple images and converts it into a (flat) single image.

 

Display

• Excise Central 2n x 2n Region: Function to excise the largest possible central square (power of 2) region of an image.
• Excise largest area rectangle from a rotated image: Function which will excise the largest possible rectangular area from an image which has been rotated.
• Extract an Intensity Profile from Image Centre to Corner: Function to extract an intensity profile from an image centre to its top right corner.
• Find Image by Title: Finds an image using its title.
• Find an Open Image from an Added Tag: Function to find an open image from an added tag
• Resize Image by Non-Integer Factors: Resizes the x and y axes of a passed-in image by any non-integer factor.
• Rotate and Crop: A function which applies a user specified rotation to the passed in image. Black space is added during rotation. This function will calculate the maximum square area on the image which excludes the added black space.
• Scale and Maximise Image: Scales the image displayed size to a particular value, then maximises the image within that display.
• Zoom to New Size: Function to zoom the passed in image to the size specified and centre it within the image frame.

 

Image Processing

• Create Temperature CLUT: A function to create a colour lookup table (CLUT) on a temperature scale.
• Find Maximum Angular Projection of an FFT: A function which measures the intensity projection of an FFT about an angular range, to determine the angular positions of the various maxima.
• Hanning Window: The Hanning Window filtering function creates a bell-shaped function with a value of unity in the centre and zero at the edges.
• Image Summing Using Matrices: A function which uses matrix maths to sum a 2D image along either its x or y axis.
• Remove Elliptical Distortion: Function which will remove elliptical distortion from a diffractogram/diffraction pattern.

 

Import/Export

• Read Bruker EDS Spectrum Text File: This function will read in an EDS spectrum text file saved using Bruker's Esprit software.
• Extract Substring from a Tab-delimited String: This function will extract a sub-string from a tab-delimited string, using the tab positions specified.
• Return a Taglist Listing the dm4 and tiff Files in a Directory: Function to return a taglist listing all the dm4 and tiff files in a directory.
• Sorts a Taglist of Filenames into Numerically Acending Order: Sorts a taglist of filenames in a directory into numerically ascending order.

 

Measurement

• Ellipse Fitting: Function which will compute the parameters of an ellipse which best fits a 2D array of points.
• Standard Deviation: Function to compute the standard deviation (sigma n-1) of an image, or a set of values passed in as pixel values in an image. The number of data points (n), the mean and the sum are also returned.
• Recursive Refinement: Function to refine a set of values by removing outliers until a target error is reached or a minimum number of points remain.

 

Scripting

• Create a UEID Taggroup: Creates a Unique Experimental ID (UEID) taggroup for linking files.