Lua is a very slow programming language - more than 20 times slower than standard C++ (which Finale® uses) and more than 60 times slower than what modern parallel programming allows for example on a quad core processor.
As MakeMusic, the creators of Finale®, did not want the plug-in to be published in fast C++, we unfortunately had to stick to Lua with its speed limitations. Hopefully MakeMusic will change its policy in the future, so we can make the plug-in much faster and even more pleasing to use.

Therefore it is recommended to use a fast computer which means a very high GHz processing frequency. It doesn't need to be a new chip or a multicore processor as Lua only use one core, only the processing frequency counts. Recommended are (overclocked) frequencies above 4,0 GHz. A comparison of some computers and how they perform with the Perfect Layout plug-in can be found here ("Do I need a faster computer for the plug-in?" in the FAQ).

When running the plug-in for the very first time, it takes a bit longer until the main dialog appears because some font metrics files are created in the background.
The auto-minimize window function is also limited on the first run as it is possible that some popup windows with questions appear. After the first run the plug-in is faster.

The Silver400/Gold400 edition are limited 400 measure and 36 (visible) staves. The plug-in won't work if your score is above that limit.

Enter all notation symbols as Finale® places them by default.
Don't waste time in manually correcting the placement of hairpins, custom lines, expressions or articulations. That's what the plug-in is for.
But make sure that the symbols were not placed ambiguously. Otherwise the Perfect Layout plug-in might not optimize the symbol's layout as it is not clear which beat or which symbol it was originally intended to connect to.

Example 1:

Image 1:
Left: Unclear on which beat the hairpin should end
Right: It should end at the end of the measure

Example 2:

Image 2: Finale's placement options are very flexible, but sometimes it is difficult to detect if a placement was intended or is faulty.
Left: Overlapping connection points. Was the hairpin intended to be in the first measure or in the second measure on beat 1? Why is mf connected to beat 3?
Right: Clear placement

Rule 1:
The plug-in will only change the placement of symbols, if it is very likely that the new position was originally intended.
(In other words: If in doubt, leave it out.)

The good news is:
The plug-in already has many rules for detecting and automatically fixing these scenarios.

For example a little offset or a little overlap usually is no problem, as in these examples:


Image 3: Overlapping hairpins that are connected to the same measure position are automatically corrected by the plug-in and horizontally optimized (at the start, the middle and the end).


Image 4: Overlapping unambiguous expressions are automatically corrected.


Image 5: Overlapping expressions and hairpins are automatically corrected.

Rule 2:
The clearer you place symbols, the better they are automatically optimized by the plug-in.
Don't be overprecise, that's the job of the plug-in.

Recommendations for optimizing your Finale® default document:
1.) Smart Shapes: Turn on "SmartShape->Snap When Attaching to Beats"
2.) Expressions: For a more uniform look it is recommended to have all expressions in an expression category use the "Category Positioning" instead of individual positioning settings. This is especially recommended for dynamic expressions, tempo marks and tempo alterations as these symbols are usually on the below or above baselines and vertically aligned.
3.) Articulations: Optimize the default placement of articulations as this is where the plug-in usually moves the articulations - except when there are collisions.
E.g. if you want to have an articulation appear below the note, don't use the placement "Position: Above Note" and move it manually below, but use "Position: Place Below".
If necessary, you need to create duplicate articulations with different placement settings.

Things to avoid:
- Having two dynamics at the same measure position (except f p which becomes fp).
- Having dynamics between hairpin start and end points (unless this is what you want).
- Having dynamics and hairpins overlap and/or connect internally different than visually (as in image 2 above).

Before applying the plug-in make sure all measures in the score and in the parts are on the staff system for the final version. Why? Because the vertical alignment of expressions and hairpins may be different, if a measure is shifted to another system. The horizontal alignment and spacing might also be handled differently if the measure layout changes.

If you have several staff systems per page, make sure you have them on the correct page as the staff and system spacing will be optimized (i.e. snap to bottom margin, no collision between staves and systems) during processing and several staff systems will have less space available than only one.

Should you want to change the measure layout afterwards, this is, of course, possible. But you should check the vertical alignment of expressions and hairpins. It is possible to re-apply the plug-in on single (or multiple) pages, staves or measures. But this is never as good as running the plug-in on the full document as not the whole document data is taken into account.

For example:
When you select a staff on a system (i.e. measure 10-13) in the score and process it with the plug-in, it will look good afterwards. But as the plug-in at the same time also processes the data in the linked part, it might worsen the measures in the part if the staff system in the part has other measures that had not been not selected (e.g. measures 9-16).
Of course, you can run the plug-in this way, you only need to be aware to check the parts afterwards.

If you have activated "Automatic Music Spacing" (Preferences->Edit->Automatic Settings->Automatic Music Spacing), skip this step.

The plug-in assumes that you have updated the music spacing before running the plug-in.
Unless you have "Automatic Music Spacing" activated, you should manually apply music spacing before runnning the plug-in (Utilities->Music Spacing->Apply ...).
Though the plug-in has a few spacing relevant correcting features (like note collision, chord collision, not enough space between hairpins and dynamics, etc.), it doesn't change the whole music spacing by default.
However there are three scenarios where music spacing is applied to some measures or even the full document:
a.) if the parts have many empty measures and the automatic creation of multi-measure rests implies a new layout,
b.) if measures have certain note layer / second collisions, chord collisions and/or slash, blank or repeat staff styles,
c.) if the plug-in option "Optimize -> Apply Music Spacing to Full Document Before Processing" is selected.

See also 9.): The "Reflow Measures" settings from the preferences are taken into account when respacing.

If you use linked parts - BTW, highly recommended as they are automatically processed by the plug-in together with the score -, you only need to one thing before running the plug-in:
after the part creation through "Document->Manage Parts->Generate Parts", parse through all parts and optimize their measure layout as described in 3.)
System spacing is currently only performed in the Score (not in the parts -> will be added in one of the next updates), so you don't need to have the systems on the correct page.
It makes more sense to do this after the symbol layout has been optimized by the plug-in.
No other manual adjustments should be done in the parts at this stage.

Excursus: Handling of Score and Parts in the Perfect Layout plug-in
Finale® has the "Edit Score" mode and the "Edit Parts" mode.
But what if a Finale® document ("Score") is actually an individual instrument part ("Part"), i.e. if it only has one staff?
The Perfect Layout plug-in automatically treats a "score" that has only one staff or a two staff-grouped system (e.g. piano) as a "part".
Certain "only in parts"-features or part-dependent parameters are automatically activated in this case.

Unfortunately it's not possible to automatically switch off music spacing through the JW Lua plug-in interface, so you need to do it manually.
It is important to switch it off, because otherwise the spacing corrections of the plug-in may be automatically removed after the plug-in has finished.

If the score doesn't have any lyrics, skip this step.

The Perfect Layout optimizes lyric baselines, i.e. it removes collisions with notes.
Because of a bug in JW Lua this is currently only possible if baselines have already been manually adjusted for each system and each lyric type (i.e. JW Lua can change a baseline offset, but it can't tell Finale® that the lyrics baseline isn't the default baseline anymore, so Finale® wouldn't notice the new baseline offset.)

In most scores this can be solved easily as they probably only use the default lyrics type: verse 1.
In this case the task can be automated when the plug-in collection TG Tools (full version) is installed. Simply click on TG Tools->Lyrics->Adjustments, Baselines... and set "Verse/chorus/section 1" to any value other than 0 EVPUs and then click on "Go".


Image 6a: TG Tools->Lyrics->Adjustments, Baselines Plug-in

This TG Tools->Lyrics->... plug-in has to be run on the score AND each part that includes lyrics. Only running TG Tools->Lyrics->... on the score is not sufficient.

If multiple lyrics types (verse, chorus, section) and/or multiple numbers haven been used or if TG Tools (full version) is not installed, the baseline has to be manually adjusted (i.e. slightly shifted to any value) for each system which is quite some effort.


Image 6b: Move the third triangle (the "Staff System" triangle) of the lyrics baseline to any (!) value to create a manual adjustment

Hopefully this bug will be fixed in a future release of JW Lua. As it has been solved partially in TG Tools, we assume that it is technically feasible and not a limitation in the Finale® PDK.

An automatic horizontal and vertical alignment of music and text symbols is only possible, if the plug-in knows what the symbol means.
The Perfect Layout plug-in uses three ways to achieve this:
a.) It includes a music font database with about 1000 music symbols from more than 450 music fonts, so it can decipher most of the music symbols.
b.) It analyzes the names of the expression categories.
c.) It compares the contents of text expressions with a few standard texts like pizz., rit., a2, crescendo, etc. and suggests to move expressions to the corresponding category if necessary.

The better the expressions are assigned to categories, the better the alignment will be.
Or in other words: Put dynamics expressions into the "Dynamics" category and tempo marks into "Tempo Marks" etc.
It doesn't matter whether there are multiple "Dynamics" or "Tempo Marks" categories or just one.

The plug-in supports to two special user-defined expression categories:
a.) "Cues": put all text expressions here that go together with cue notes or that are just cue texts like "Fl.1", "Perc.", "Vln.2+Vla.", etc.
b.) "In Parts Only": put all text expressions here that shall only be visible in the parts. The plug-in will hide them in the score.
The name of these special categories can be adjusted in the plug-in's settings.


Image 7: "Cues" category


Image 8: "In Party Only" category

If niente circle expressions are not used in the score, skip this step.

Niente hairpins in Finale® are usually constructed with a "circle" expression and a hairpin.
The Perfect Layout plug-in automatically connects them visually.
To improve the look, the niente expression should have an opaque enclosure, so that the hairpin is not visible through the circle.

The plug-in automates this process and has three requirements:
a.) The circle can be an "o", "O" or "0" symbol from any text font or a "o" symbol from any supported music font.
b.) The expression must be located in the "Dynamics" category.
c.) Select any (!) enclosure in the expression designer dialog (unfortunately it's not possible to this through a plug-in). Don't click on "Edit" or specify the enclosure settings. This will be done automatically by the plug-in. Just select an enclosure like "Square" or "Circle" (see image 7). Then click on ok.


Image 9: Enclosure "Square" selected


Image 10: Before and after running the plug-in
The square enclosure is automatically reduced to the size of the niente circle.

The Perfect Layout plug-in reminds the user to run other layout plugins like Patterson Beams (Beam Optimization) or JW Yada Yada (Tremolo/Beam/Stem Optimization).
These should be run before the Perfect Layout plug-in as they influence the final layout, vertical spacing and collisions.
Running them afterwards can introduce new collisions or result in an unbalanced staff spacing.

Please set the "Reflow Measures" options in the preferences according to your needs. If required, also add page breaks.

When the document spacing is changed by the plug-in, it will use these settings. Except when only "Do Not Reflow" is selected: "Do Not Reflow" is temporarily overridden with "Only Within Systems" - otherwise the plug-in doesn't make sense.
"Only Within Systems" means that any spacing changes will only affect the measures on the same systems, but not the other systems.
Selecting "Across Systems" can lead to measures being moved to another system and "Reflow Systems Across Pages" even moves full systems to other pages if there is enough space. Dependent on the quality of the manual measure layout (see above), either of them may be the best solution.

If your linked parts have many empty measures and don't have multi-measure rests yet, it is recommended to have "Reflow Systems Across Pages" and "Across Systems (Remove System Locks)" activated, so that the measure layout is completely redone in the parts.

Note: If you use "Across Systems" with the plug-in, it will automatically reset the reflow setting at the end of the processing to "Only Within Systems". Otherwise the document layout would be destroyed too easy after the processing.


Image 11a: Finale's Reflow Measures settings under Preferences->Edit

Please set the "Manual Positioning" option in Document Options->Music Spacing according to your needs.

If it is set to "Clear" or "Ignore" the manual positioning might be removed. If it is set to "Incorporate", the manual positioning will be kept unless there are collisions.

The automatic system and staff balancing forces the systems to stretch until the page bottom margin. So you need to set a good value bottom margin now. You can change it later for alignment of page text objects. Now it is only needed as a marker for bottom of the staves.

In the plug-in settings you have three alignment options:
a.) Align the page bottom margin with the bottom staff line.
b.) Align the page bottom margin the lowest element on the bottom staff.
c.) Align the page bottom margin with the bottom staff line plus a fixed margin.

Note:
The plug-in doesn't perform any collision detection with page text elements and systems.
Very often the first page of the score has a large copyright notice at the bottom.
In this case the bottom margin of the first page must be set above the copyright notice, so it will mark the lowest position of the system. The first bottom margin will also be above the bottom margins of the following pages (see image 14).
When changing the bottom margin by mouse, make sure to select "Adjust Current Page Only" on the first page (by right-clicking the mouse). Then the other bottom margins will remain unchanged.


Image 14: The systems will be aligned to the bottom margin of a page

Before running any plug-in always make sure to save the Finale® document file for the unlikely case of an abrupt termination of the plug-in or even a crash of Finale®.

A termination of the plug-in usually comes with this error message:

Image 12: Plugin Termination Error

Please contact support should this occur. Usually this can be fixed quite easily, but it requires sending in the Finale® document to find out where exactly the error has occured.

Five types of crashes are known of which three are relevant for the Perfect Layout plug-in:
a.) If the plug-in is run in Finale® 2014/2014.5, it can crash in "huge" scores because of a limited 32bit memory.
Unfortunately we haven't found out yet what the exact limit for a "huge" score crash is.
The smallest files that crashed Finale® were about 1,5 MB of size, held about 50 or more staves and typically at least 300 measures.
But there have also been many files of more than 4 MB in size, about 40 staves and 200 measures that didn't crash Finale® 2014. So it's probably not the file size, but the number of staves, measure and note entries that leads to the crash ("Frames" in Finale's statistics dialog).
How to prevent this: these crashes don't occur in Finale® 25 / 64 bit.
b.) Corrupt Finale® documents can crash the plug-in. In our beta tests this occured only in Finale® documents that also crashed other third party plugins or Finale's own plugins. So it seems to be a Finale® problem.
c.) Every now and then (about every 100.-200. plug-in call without closing Finale®) the plug-in crashes Finale® because of a "Measure Number Region" error. It seems to be a bug in the JW Lua PDK, but it hasn't been located yet. In this case simply restart Finale® and rerun the plug-in - it won't occur again.
d.) The JW Lua plug-in interface has a few known cases where it can crash Finale®. Neither of them is implemented in the Perfect Layout plug-in, so this shouldn't occur.
e.) Yet unknown crashes might occur. Not very likely, but not impossible.
In case of a crash, restart Finale® and try to run the plug-in again - most probably it was the "Measure Number Region" crash which occurs irregularly. Should Finale® crash again, please contact our support.

It is recommended to run the plug-in on the full document in "Edit Score" mode as only this activates all features and also processes all parts. You can either manually select the full document before running the plug-in or select nothing which will automatically select all. The plug-in can be run in Scroll or Page View.

There are two ways to start the plug-in:
1.) Standard: Click on Plug-ins->JW Lua->ES Perfect Layout.


Image 13: Starting the plug-in

2.) Within JW Lua: this is described here.

Features that will only work in full document mode:
- System and staff balancing (also works if a full page is selected)
- Optimization of expression default positions and default categories (e.g. for MusicXML import)
- Expression baseline changes
- Updates on measure number ranges in multi-measure rests
- Invalid slur deletion
- Fixing weird top staff margins after staff deletion

The plug-in will remind the user of all tasks listed above (1. - 11.) by default.
It is possible to turn of these reminder dialogs (General->Bypass All Warning Dialogs)
But it is highly recommended to keep them in as it is very likely that one has forgetten one or two things before running the plug-in.

Should you notice that other plug-in parameters might work better or that you had forgotten anything before running the plug-in, you can undo it and rerun it with new parameters.

It is also possible to run the plug-in multiple times.
When running the plug-in multiple times with same parameters (well, that doesn't make sense, but anyway...), the results are usually not identical, but in general they do not improve the layout a second time. Especially hairpins might change their start or end position a second time when called twice, so that they move further away from their original position which isn't known anymore in the second call.
The staff and system spacing is very likely to change when the plug-in is applied multiple time as already tiny deviations in the layout might result in small changes in the spacing algorithm. This is due to the iterative approach in the spacing algorithm.

Clicking on Undo/Redo for a fast before/after comparison of the plug-in is possible, but unfortunately it does not always work well when a lot of respacing has been done by the plug-in.
There is also a known bug, where page breaks in parts may lead to staff systems disappearing in the score when clicking on "Redo".
For a yet unknown reason (we assume a bug in the Finale® PDK or the JW Lua PDK) the page layout is sometimes not updated when calling "Redo", so the spacing will get messed up on "Redo".
If the spacing hasn't been changed much, undo/redo works fine.

If any manual adjustments are still required, now the time has come.
It's also possible to re-apply the plug-in on selected areas, if any manual adjustments were made that could be improved by a selective rerun.

The following Finale® preferences and document options will change through the plug-in:
If the measure reflow option "Edit->Preferences->Across Systems (Remove System Locks)" was activated, it will become "Across Systems (Maintain System Locks)" to not destroy the layout that the plug-in has created.
"Edit->Preferences->Automatic Update Layout" will be turned off to maintain the new page layout created by the plug-in.
If the document option "Multi-Measure Rests->Update Automatically" was activated, it will be turned off to keep the new multi-measure rest layout.

Don't forget to reset the Finale® preferences according to your needs for other documents!
Finale® doesn't save "Edit->Preferences"per Finale® document, but only globally. So you may have to adjust tese values for your next document.