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 longer until the main dialog appears because some font metrics files are created in the background.
If you have many text fonts installed (especially huge unicode fonts), the metrics file creation process can take more than a minute (even 20 minutes if you have very, very many text fonts installed and use a slow computer). It's also possible that you will see a few black windows pop up during that process.

The external progress bar and 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 much faster as this process only has to be done once.

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 5.)
System spacing is currently only performed in the score and in extracted parts (but not in the linked parts -> this 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.

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 Parts 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.

Perfect Layout includes many automatic optimizations for MusicXML imported documents or old Finale documents. The main function is automatic expression category assignment and automatic alignment of the expressions.
However this only works if the plug-in is 100% sure that an expression belongs to a certain expression category or needs a certain alignment.
This works fine for simple expressions like "a tempo", "arco" or all dynamic expressions. But it becomes difficult on ambiguous text expressions that could be either tempo marks, tempo alterations or expressive text.

Our suggestion: if your score only uses the "standard" text expressions, just run the plug-in without changing any expression category assignments manually.
In other cases you could try what happens in the plug-in without manually correcting the expression category assignment. Should you notice that some text expressions don't get a proper placement, you could undo the plug-in, correct the expression category assignment manually and then run it again.

Note: If you correct the expression category assignment manually, you usually get a better placement if you select to "Use ... Category Positioning" (see image 11a).


Image 11a: "Use Tempo Marks Category Positioning" in the Expression Designer dialog

There may be situations where you have placed expressions in the score that the plug-in should not move at all.
For example in very dense scores, technique or dynamic expressions might need a very special placement in order for the systems to fit on the page. Should you notice that the plug-in doesn't perform a good placement by itself, you can exclude expressions from plug-in processing.

Note: if you have expressions that should be exluded at some places, but not everywhere, you need two expression definitions. Duplicate the original expression definition first and use the EXCLUDE expression only where required.

The opposite is the command FORCEINCLUDE: if you have huge text expressions far above/below the staff, they are ignored by default for vertical alignment and/or vertical spacing.
If you add FORCEINCLUDE to the description text, they will be included although this might result in huge vertical staff distances.

Example: To exclude an expression simply add EXCLUDE to the description in the Expression Designer dialog:
Image 11b: Adding EXCLUDE to the description

A third option is to add ALLOWSHIFTRIGHT to text expressions (probably some technique text expressions) to allow that they are shifted to the right of dynamics on the same measure position.

Sometimes a shift to the right is performed automatically, even without ALLOWSHIFTRIGHT:
Expressive text expressions are always shifted to the right.
If the start point of the expression didn't become unclear through the shift to the right, then the expression would also be shifted automatically.
In image 11c adding ALLOWSHIFTRIGHT is necessary, as the short 8th notes otherwise make the start point unclear.
Note: It might be better if you put the technique expression above the staff, if there are no other expressions, to make the start point even more clear.
For more examples of multi-expression collisions see here.


Image 11c: Without (left) and with ALLOWSHIFTRIGHT text

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.

If you have a huge document which uses "real whole rests" in thousands of measures instead of Finale's default whole rests (which are only visible, but no real note entries), then it is recommended to run Finale's own "Change to Default Whole Rests" plug-in before running Perfect Layout. This is much (!) faster than the JW Lua implementation which may take several minutes on huge scores.
On smaller scores, like 100 measures and 20 instruments, it doesn't make a big difference.
Usually there is no reason to use "real whole rests" in Finale, that's why Perfect Layout optimizes them to the default setting.

The "Reflow Measures/Systems" settings in Finale's own preferences are crucial for Perfect Layout's measure and system layout! So please set the "Reflow Measures" options according to your needs before running the plug-in. If required, also add page breaks to the document.

When the document spacing is changed by the plug-in, it will use these reflow 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. So all measures will remain in their system and not jump to the next system.

Selecting "Reflow Across Systems" can lead to measures being moved to another system and "Reflow Systems Across Pages" even moves full systems to the next page if there is enough space.

Dependent on the quality of your manual measure layout (see above), either of these options may be the best solution:
If you have already created a manual measure layout (i.e. making the correct page turns, etc.), then "Only Within Systems" and not "Reflow Systems Across Pages" is probably the best setting.

If you have created a measure layout for each system, but no page layout, then "Only Within Systems" AND "Reflow Systems Across Pages" is the way to go.

If you have a few systems that are already locked, "Across Systems (Maintain System Locks)" might be your choice.

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 11c: 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.

Of course, it's possible to run the plug-in both in "Concert pitch" and in "Transposed Pitch" mode.
However, before running the plug-in, you should adjust the score and the parts to the pitch that you want to use later at print time.
Otherwise the vertical/horizontal alignments and music spacing adjustments created by the plug-in may not fit optimally if you change the display mode later (e.g. because more accidentals require more space, because of very low notes, because of other key signatures, etc.).

If you still want to change the pitch mode after running the plug-in, you can, of course, do it.
If necessary, it's possible and recommended to run the plug-in again - either on the full score or on selected parts only.

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

If you use Finale 26, you should pay attention to the new Finale 26 features "articulation stacking" and "slur collisions with articulations". As MakeMusic hasn't release the Finale 26 plug-in software yet (and thus JW Lua hasn't been updated to these new features), these new features can't be detected by the plug-in.
So it might look better (or worse - just as you prefer it) if you switched off "Stacking" and set "Slur Interaction: Auto inside/outside" to "Ignore" before applying the plug-in.

Also make sure to select "Keep Positioning" of articulations when opening a document from a previous version of Finale®. If you select "Enhance" instead, some articulations might not be fixed.

Don't forget that new documents created with Finale 26 are NOT compatible with Finale 25 anymore (not in general, but the articulation placement will be messed up when you load the document in a previous Finale version). This doesn't have to do with plug-ins, but with the new articulation feature and the way Finale saves articulations. So if you plan to use the document in Finale 25 or Finale 2014, don't create it with Finale 26, but with Finale 25.

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 off 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 forgotten 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.
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 these values for your next document.