dbstop('in', filename, 'at', location, 'if', 'tracer()');

We can use this same technique for other purposes. For example, if we want to do some action (not necessarily log – perhaps do something else) when a certain code point is reached. The benefit here is that we don’t need to modify the code at all – we’re adding ad-hoc code pieces using the conditional breakpoint mechanism without affecting the source code. This is particularly useful when we do not have access to the source code (such as when it’s compiled or write-protected). All you need to do is to ensure that the instrumentation function always returns false so that the breakpoint does not become live and for code execution to continue normally.
The tracer4m utility is quite sophisticated in the sense that it uses mlint and smart regexp to parse the code and know which functions/methods occur on which line numbers and have which type (more details). In this sense, Per used undocumented functionality. I’m certain that Jiro was not aware of the dependency on undocumented features when he posted about the utility, so please don’t take this to mean that Jiro or MathWorks officially support this or any other undocumented functionality. Undocumented aspects are often needed to achieve top functionality, and I’m happy that the POTW blog highlights utilities based on their importance and merit, even if they do happen to use some undocumented aspect.
tracer4m‘s code also contains references to the undocumented profiler option -history, but this is not in fact used by the code itself, only in comments. I use this feature in my profile_history utility, which displays the function call/timing history in an interactive GUI window. This utility complements tracer4m by providing a lot more information, but this can result in a huge amount of information for large and/or long-running programs. In addition, tracer4m has the benefit of only logging those functions/methods that the user finds useful, rather than all the function call, which enables easier debugging when the relevant code area is known. In short, I wish I had known about tracer4m when I created profile_history. Now that I know about it, maybe I’ll incorporate some of its ideas into profile_history in order to make it more useful. Perhaps another moral of this is that we should actively monitor the POTW blog, because true gems are quite often highlighted there.

Function call timeline profiling

The post Runtime code instrumentation appeared first on Undocumented Matlab.

Goals of export_fig

1. Publication quality

   I wrote export_fig to produce nice looking figures for my PhD thesis and journal papers. The two standard MATLAB functions for exporting figures are saveas and print. Unfortunately, the quality of their default outputs just wasn’t good enough. For example, images in PDF outputs would be heavily compressed and I wanted control over image quality.
   eps2pdf (which is part of the export_fig package) takes a quality setting as input, and converts this into suitable settings for ghostscript to convert the EPS file to a PDF, allowing users to get much higher fidelity output. In addition, ghostscript also crops the figure border to the EPS bounding box, and embeds fonts in the PDF. This last feature is obligatory for some publications, and export_fig is sometimes recommended by conferences or journals for this reason. Control of JPEG quality is achieved by passing the quality option to imwrite in export_fig.m.
   In export_fig.m, I also added anti-aliasing for raster outputs (by exporting at a higher resolution and downsizing), and alpha-matting (by exporting with both black and white backgrounds to compute transparency) for PNG outputs. The alpha-matting feature allows textured backgrounds to show through the exported figure, which can be useful for presentation slides. Here is an image that demonstrates such alpha-matting:
   

   

2. WYSIWYG (what you see is what you get)

   Another issue with saveas and print is that, by default, they do not reproduce a figure exactly as it appears on screen. The dimensions change, the aspect ratio changes, the amount of whitespace changes, the background color changes, the axes ticks change, line dash lengths change, the fonts change, etc. All these changes are generally-undesirable side-effects of those functions.
   export_fig avoids these changes to the figure, ensuring that it gets exported as faithfully as possible to the on screen visualization. export_fig uses print under the hood, but changes various figure and axes settings to get the desired result. For example, in export_fig.m I call set(fig,'InvertHardcopy','off'), which ensures that the background color doesn’t change. I also set the axes Limits and Tick modes to 'manual', to ensure that axes don’t change. Similarly, in print2eps.m, I call set(fig, 'PaperPositionMode','auto', 'PaperOrientation','portrait') to ensure that the figure dimensions don’t change for vector outputs.
   Two of the changes, line dash lengths and fonts, are caused by the Painters renderer, and so they only occur in vector output. The only way to fix these issues was to edit the EPS file that print generates: fix_lines.m changes the definition of dash lengths in the EPS file, so that the dash lengths depend on the line widths. Likewise, print2eps.m changes unsupported fonts in the figure to supported ones, then reinserts the unsupported font into the EPS. Unfortunately this doesn’t work so well when the two fonts have different character widths.
   In addition to these features, the MATLAB rendering pipeline (in both HG1 and HG2 versions) is full of bugs. Many lines of code in export_fig are dedicated to circumventing these undocumented bugs. For example, lines 249-273 of today’s export_fig.m:

   % MATLAB "feature": black colorbar axes can change to white and vice versa!
   hCB = findobj(fig, 'Type', 'axes', 'Tag', 'Colorbar');
   if isempty(hCB)
       yCol = [];
       xCol = [];
   else
       yCol = get(hCB, 'YColor');
       xCol = get(hCB, 'XColor');
       if iscell(yCol)
           yCol = cell2mat(yCol);
           xCol = cell2mat(xCol);
       end
       yCol = sum(yCol, 2);
       xCol = sum(xCol, 2);
   end
   % MATLAB "feature": apparently figure size can change when changing colour in -nodisplay mode
   pos = get(fig, 'Position');
   % Set the background colour to black, and set size in case it was changed internally
   tcol = get(fig, 'Color');
   set(fig, 'Color', 'k', 'Position', pos);
   % Correct the colorbar axes colours
   set(hCB(yCol==0), 'YColor', [0 0 0]);
   set(hCB(xCol==0), 'XColor', [0 0 0]);
   

   Similarly, lines 143-160 of today’s print2eps.m:

   % MATLAB bug fix - black and white text can come out inverted sometimes
   % Find the white and black text
   black_text_handles = findobj(fig, 'Type', 'text', 'Color', [0 0 0]);
   white_text_handles = findobj(fig, 'Type', 'text', 'Color', [1 1 1]);
   % Set the font colors slightly off their correct values
   set(black_text_handles, 'Color', [0 0 0] + eps);
   set(white_text_handles, 'Color', [1 1 1] - eps);
   % MATLAB bug fix - white lines can come out funny sometimes
   % Find the white lines
   white_line_handles = findobj(fig, 'Type', 'line', 'Color', [1 1 1]);
   % Set the line color slightly off white
   set(white_line_handles, 'Color', [1 1 1] - 0.00001);
   % Print to eps file
   print(fig, options{:}, name);
   % Reset the font and line colors
   set(black_text_handles, 'Color', [0 0 0]);
   set(white_text_handles, 'Color', [1 1 1]);
   set(white_line_handles, 'Color', [1 1 1]);
   

Design philosophy

The export_fig toolbox is just a collection of functions. I put code into a separate function when either:

1. One might want to use that functionality on its own, or
2. That functionality is required by two or more other functions.

Subfunctions are used for code called multiple times in only one file, or where it improves legibility of the code.
The easiest way to understand the structure of the export_fig toolbox is to visualize the tree of function dependencies within the toolbox:

1. export_fig

   This is the main function in the toolbox. It allows exporting a figure to several different file formats at once. It parses the input options. If only a subset of axes are being exported then it handles the transfer of these to a new figure (which gets destroyed at the end). It makes calls to print2array() for raster outputs, and print2eps() for vector outputs. For raster outputs, it also does the downsampling if anti-aliasing is enabled, and alphamatte computation if transparency is enabled. For vector outputs, it also does the conversion from eps to pdf, and also pdf back to eps. The reason for this last conversion is that the pdf is cropped, compressed and has the fonts embedded, and eps outputs should get this too (though I don’t think the font embedding remains).

2. print2array

   This function rasterizes the figure. If the painters algorithm is specified then it calls print2eps(), then rasterizes the resulting EPS file using ghostscript. If another renderer is specified then this function just calls print() to output a bitmap. Finally, borders are cropped, if requested.

3. print2eps

   This function calls print() to generate an EPS file, then makes several fixes to the EPS file, including making dash lengths commensurate with line width (old graphics system (HG1) only, i.e. R2014a or earlier), and substituting back in unsupported fonts.

4. crop_borders

   Crops away any margin space surrounding the image(s): Given an image or stack of images (stacked along the 4th dimension), and a background color, crop_borders() computes the number of rows at the top and bottom and number of columns on the left and the right of the image(s) that are entirely the background color, and removes these rows and columns.

5. ghostscript

   This function looks for a Ghostscript executable. or asks the user to specify its location. It then stores the path, or simply loads the path if one is already stored. It then calls the Ghostscript executable with the specified arguments.

6. fix_lines

   This function makes dash lengths commensurate with line width, and converts grid lines from dashes to circular dots, in EPS files generated by MATLAB using HG1 (R2014a or earlier). fix_lines is also available as a separate File Exchange utility (selected for Pick-of–the-Week, just like export_fig). This function is no longer required in HG2 (R2014b or newer) – see below.

7. read_write_entire_textfile

   Does what it says, reading or writing and entire text file from/to disk to/from memory, but handles errors gracefully, not leaving files open.

8. eps2pdf

   This function converts an EPS file into a PDF file using Ghostscript.

9. pdf2eps

   This function converts a PDF file into an EPS file using pdftops, from the Xpdf package.

10. pdftops

    Does exactly the same thing as the ghostscript function, but for the pdftops executable instead.

11. user_string

    This stores or loads user-specific strings in text files. This allows user-specific values to propagate across different versions of MATLAB, whilst avoiding these values being stored in version controlled code.

12. copyfig

    This function simply creates a copy of a figure, like the built-in copyobj(). However, because the latter has some bugs, this function, which saves the figure to disk then opens it again, is required. Indeed, much of the code within the toolbox is simply circumventing bugs in MATLAB functions.

13. isolate_axes

    This function removes unwanted axes from a figure. The approach to exporting a subset of axes is to copy the figure then remove the unwanted axes. Again, this is to circumvent bugs in the builtin function copyobj().

14. using_hg2

    This function provides a robust way of checking if HG2 is in use (HG1 is the default in R2014a or older; HG2 is the default in R2014b or newer).
    In HG2, the entire rendering pipeline has changed. While most of the features remain the same, the bugs have completely changed. For example, dash lengths in HG2 vector output are now sensible, so fix_lines is not required. However, in R2014b at least, patch-based graphics generate bloated EPS files, and line widths cannot go below 0.75pt. Finally, an obvious change for raster output is that it is smoothed by default, so anti-aliasing is not required; the default settings in the parse_args() function within export_fig.m reflect this.

15. append_pdfs

    export_fig does have a -append option, but this gets slower the larger the appended file becomes. A quicker way of generating a multipage PDF from several figures is to export them all to separate PDFs, then use this function to combine them into one in a single go. Also available as a separate File Exchange utility.

16. im2gif

    This function converts a stack of images, or a multi-image TIFF file, to an animated GIF. export_fig can generate multi-image TIFFs using the -append option, making generating animated GIFs straightforward. Also available as a separate File Exchange utility.

And that’s it! All the functions have help text describing their input and output arguments.

Editorial notes

After several year of creating, improving and maintaining export_fig, Oliver is unfortunately no longer able to maintain this utility. As Oliver mentioned above, I (Yair) have volunteered to try to step into his shoes and maintain it. As Oliver’s detailed description (which barely scratches the surface) shows, this is certainly not a trivial utility. It will take me some time to get up to speed with all the internal technical details, so please be patient…
Readers interested in high-fidelity export might also consider using my ScreenCapture utility. Unlike export_fig, which uses Matlab’s builtin print function to generate (and fix) the output, ScreenCapture uses the standard java.awt.Robot.createScreenCapture() to take an actual screen-capture of the requested figure, axes or window area and then saves this to file/clipboard or sends it to the printer. In a sense, the export_fig and ScreenCapture utilities nicely complement each other.

The post export_fig appeared first on Undocumented Matlab.

>> jButton = com.mathworks.mwswing.MJToggleButton;
>> checkClass(jButton)  % or: jButton.checkClass
Class com.mathworks.mwswing.MJToggleButton (uiinspect)
Superclass: javax.swing.JToggleButton
Methods in MJToggleButton missing in JToggleButton:
   hasFlyOverAppearance() : boolean
   hideText()
   isAutoMnemonicEnabled() : boolean
   isTextHidden() : boolean
   setAutoMnemonicEnabled(boolean)
   setFlyOverAppearance(boolean)
   setFocusTraversable(boolean)
   unHideText()
Methods inherited & modified by MJToggleButton:
   getForeground() : java.awt.Color
   getParent() : java.awt.Container
   isFocusTraversable() : boolean
   paint(java.awt.Graphics)
   setAction(javax.swing.Action)
   setModel(javax.swing.ButtonModel)
   setText(java.lang.String)
Interfaces in JToggleButton missing in MJToggleButton:
   javax.accessibility.Accessible
Interfaces in MJToggleButton missing in JToggleButton:
   com.mathworks.mwswing.ExtendedButton

The interpretation is quite intuitive. For example, isTextHidden() is a class method that accepts no input args and returns a boolean result; setText() is a method that accepts a string and returns no result.
Each of the hyperlinks is linked to another checkClass on the specified class. This makes investigation of classes and their interconnections quite easy.
From this output, we learn that the MathWorks MJToggleButton class added the FlyOverAppearance and AutoMnemonicEnabled properties, together with their associated accessor methods. We also learn that MJToggleButton added a non-property method: hideText().
Finally, setFocusTraversable() was added as a setter method to the FocusTraversable property: the getter method isFocusTraversable() is already defined in the ancestor JToggleButton class (which is part of the standard Swing package) – MJToggleButton simply added a setter method.
Some classes (e.g., MJSlider) appear to be plain wrappers for their Swing ancestor:

>> checkClass('com.mathworks.mwswing.MJSlider')
Class com.mathworks.mwswing.MJSlider (uiinspect)
Superclass: javax.swing.JSlider
Methods inherited & modified by MJSlider:
    setModel(javax.swing.BoundedRangeModel)
Interfaces in JSlider missing in MJSlider:
    javax.accessibility.Accessible
    javax.swing.SwingConstants

In other cases, MathWorks has extensively modified the base class functionality:

>> checkClass com.mathworks.mwswing.MJToolBar
Class com.mathworks.mwswing.MJToolBar (uiinspect)
Superclass: javax.swing.JToolBar
Methods in MJToolBar missing in JToolBar:
   addGap()
   addGap(int)
   addToggle(javax.swing.Action) : javax.swing.JToggleButton
   configure(com.mathworks.mwswing.ExtendedButton) (static)
   configureButton(com.mathworks.mwswing.MJButton) (static)
   configureButton(com.mathworks.mwswing.MJToggleButton) (static)
   configureButton(com.mathworks.mwswing.MJToggleButton, boolean) (static)
   createMacPressedIcon(javax.swing.Icon) : javax.swing.Icon (static)
   dispose()
   dispose(javax.swing.JToolBar) (static)
   getComponentExcludingMoreButton(int) : java.awt.Component
   getFlyOverBorder() : javax.swing.border.Border (static)
   getToggleFlyOverBorder() : javax.swing.border.Border (static)
   isFloating() : boolean
   isMarkedNonEssential(javax.swing.JComponent) : boolean (static)
   isMorePopupEnabled() : boolean
   isOnMoreMenu(java.awt.Component) : boolean
   markAsNonEssential(javax.swing.JComponent) (static)
   setArmed(boolean)
   setInsideToolbarBorder()
   setMorePopupEnabled(boolean)
Methods inherited & modified by MJToolBar:
   add(javax.swing.Action) : javax.swing.JButton
   addSeparator()
   addSeparator(java.awt.Dimension)
   doLayout()
   getMinimumSize() : java.awt.Dimension
   getPreferredSize() : java.awt.Dimension
   removeAll()
Interfaces in JToolBar missing in MJToolBar:
   javax.accessibility.Accessible
   javax.swing.SwingConstants
Static fields in MJToolBar missing in JToolBar:
   MORE_BUTTON_NAME                  = 'MoreButton'
   MORE_MENU_INELIGIBLE_PROPERTY_KEY = 'MoreMenuIneligible'
   NON_ESSENTIAL_PROPERTY_KEY        = 'NonEssentialComponent'
Sub-classes in MJToolBar missing in JToolBar:
   com.mathworks.mwswing.MJToolBar$VisibleSeparator

In this example, we see that the MJToolBar class includes 3 variants for the configureButton() method, and 2 variants for the dispose() method, accepting a different number and/or type of input parameters.
Similarly, for the CheckBoxList class:

>> checkClass com.mathworks.mwswing.checkboxlist.CheckBoxList
Class com.mathworks.mwswing.checkboxlist.CheckBoxList (uiinspect)
Superclass: com.mathworks.mwswing.MJList
Superclass: javax.swing.JList
Methods in JList missing in CheckBoxList:
   JList(java.lang.Object[])
   JList(java.util.Vector)
Methods in CheckBoxList missing in JList:
   CheckBoxList(java.util.List)
   checkAll()
   checkIndex(int)
   checkValue(java.lang.Object)
   constrainViewerToCellHeight() : boolean
   getCellPainter(java.lang.Integer) : java.awt.Component
   getCellPainter(java.lang.Object) : java.awt.Component
   getCellViewerOffset(java.lang.Integer) : java.awt.Dimension
   getCellViewerOffset(java.lang.Object) : java.awt.Dimension
   ...

Here we see that two superclass constructor variants (accepting an array of Objects or a single Vector object) have been replaced by a single constructor that accepts a List object (this is considered a bad programming practice, by the way).
In this case, CheckBoxList extends MJList which is also a Matlab class, which itself extends the standard Swing JList. By default, checkClass compares the specified class object versus the nearest ancestor class that is non-MathWorks. We can modify this behavior by specifying a different super-class level:

>> checkClass('com.mathworks.mwswing.checkboxlist.CheckBoxList', 1)  % compare CheckBoxList to com.mathworks.mwswing.MJList
>> checkClass('com.mathworks.mwswing.checkboxlist.CheckBoxList', 2)  % compare CheckBoxList to javax.swing.JList (=default behavior)
>> checkClass('com.mathworks.mwswing.checkboxlist.CheckBoxList', 3)  % compare CheckBoxList to javax.swing.JComponent (=JList's superclass)
>> checkClass('com.mathworks.mwswing.checkboxlist.CheckBoxList', 4)  % compare CheckBoxList to java.awt.Container (=JComponent's superclass)
% ...and so on (up to java.lang.Object, which is the base class for all Java objects)

checkClass can inspect both class name and class objects. For example:

checkClass('java.lang.String')   % class name
checkClass(javax.swing.JButton)  % class object
jButton = javax.swing.JButton('Click me!');
jButton.checkClass;  % class object
checkClass('com.mathworks.mwswing.MJToolBar')  % class-name
checkClass(com.mathworks.mwswing.MJToolBar)    % class object
checkClass(com.mathworks.mde.desk.MLDesktop.getInstance)

Class methods can also be inspected using methodsview or preferably uiinspect; properties and callbacks can be inspected by using get, inspect, or again uiinspect. Users may also try to search the Matlab-supplied m-files for sample usage of these classes. For example, Matlab 7.2’s uisetfont.m uses com.mathworks.mwswing.MJButton. Note that different Matlab releases use internal classes differently. Therefore, searching the m-file code base of different Matlab releases may yield additional clues.
I encourage you to download the checkClass utility and explore its code, and I welcome your feedback.
p.s. – Anyone watching the TV series “The Americans” may have noticed that in the season finale (“Echo“), which aired on May 21, the code listing of the Echo program, is actually that of a GUIDE-created Matlab m-file (linear_array_gui), plus some non-Matlab code (Ada?). Matlab’s GUIDE wasn’t available in the mid-1980s, when the story purportedly takes place, back in the days of a 640KB IBM PC with a single floppy drive, but it’s a nice anachronism. In any case the combination of the Matlab and Ada code would never have run… 🙂

The post checkClass appeared first on Undocumented Matlab.

Java solutions for spreadsheet access

Luckily, the community of Java developers, which is an order of magnitude larger than the Matlab community, has developed several utilities that we can easily use in Matlab to implement xlswrite‘s functionality on Macs, Linux, and wherever else Matlab may run – even Windows, if we really wish. Most articles on this website that deal with Java focus on its GUI aspects, i.e., how to use Java to improve Matlab’s plain-vanilla appearance/behavior. But Java is in fact a very broad programming platform that has an enormous repository of non-GUI solutions: networking, database support, data structures, computational algorithms, etc. etc. – and a huge number of them are open-source. Unlike Java’s GUI goodies, these Java packages, being non-GUI in nature, are fully supported by Matlab.
The Excel spreadsheets support, and Office support in general, is just another example of the wide range of non-GUI packages available in Java. In fact there are full-fledged Office lookalikes written in Java (most notably the open-source OpenOffice). We can either use these applications directly, or interact with them from Matlab (via Java), just as we can interact with Excel on Windows.
There are several Java packages that enable reading and writing spreadsheet data, without the full-blown Office support. One such open source project is the ODF (Open Document Foundation) Toolkit, which has plenty of online resources. In 2010 a Matlab user contributed a utility to use the ODF Java package for reading and writing ODF-format spreadsheets (*.ods). Other users have also provided ODF utilities for Matlab.
Using ODF is excellent and cross-platform, but does not solve the Excel problem directly, because the ODF format is incompatible with the XLS format. We can use another open-source Java package, JExcelApi, for this. JExcelApi is relatively easy to use and has several online tutorials (example1, example2), although it is not as widely used as ODF.
Another open-source Java package that can be used to directly read and write XLS files is Apache POI. An informal comparison of POI and JExcelApi can be found here.

xlwrite

Very recently, Marin Deresco has posted a Matlab utility called xlwrite that uses JExcelApi for implementing an xlswrite variant that can be used on all Matlab platforms.

After downloading xlwrite, we need to add its two contained JAR files (jxl.jar, MXL.jar) to the Java classpath:

javaaddpath('C:/Yair/Utils/JExcelAPI/jxl.jar')
javaaddpath('C:/Yair/Utils/JExcelAPI/MXL.jar')

We can now use xlwrite to store data in a real *.xls file:

xlwrite('my_data.xls', magic(3))

xlwrite has similar syntax and inputs to Matlab’s xlswrite. It can also write 3-d arrays (which xlswrite cannot), of cell and double type (the third dimension is simply stored in separate worksheets).
Note: Matlab’s decimal separator is ‘.’ – in order to be able to work with exported data on Macs, Mac users may need to change Mac decimal separator preferences. To do so you need to go to System Preferences > International > Formats and click on Customize button in the number zone, then type ‘.’ in the required field.
xlwrite is a real working solution. However, it may need further refinements, that will hopefully be added in future updates to this utility:

• automatically add the javaaddpath commands to xlwrite so that users won’t need to do them
• manage Java heap space, as Java heap memory saturates for large arrays exported many times (possible memory leak)
• format dates and strings, as all numbers appear as text in Excel
• optimize performance (the culprit appears to be a non-vectorized Cell2JavaString function)
• include formatting and other goodies that the current xlswrite does not

The post xlswrite for Mac, Linux appeared first on Undocumented Matlab.

The post Specialized Matlab plots appeared first on Undocumented Matlab.