PolyBevel Grabber for modo

Introduction

Poly Bevel Grabber is a script that will 'grab' a series of points in any orientation and convert those points into a bevel shape for immediate use and/or for integrating with my Poly Bevel Presets v1.5 script. Here's the key features:

Grabs up to 50 vertices anywhere and converts the points into a bevel shape.

The resultant shape can be used immediately, is stored until you grab another shape and can be converted into a macro.

The grabbed bevel shape can be used at any scale you choose.

The grabbed shape can be instantly flipped on it's inset or shift.

You can effectively 'draw' bevel profiles directly in viewports in the context of your geometry at any angle using the vertex or pen tool.

The bevel shape can be integrated directly into my PolyBevel Presets v 1.5 script to be used at any scale.

You can use Poly Bevel Grabber to 'populate' presets for use with Poly Bevel Presets v 1.5

Movies

Basic Functionality (3.7Mb Quicktime)
Drawing Bevels (800k Quicktime)
Drawing Bevels at Angles (2.1Mb Quicktime)

How Do I Use It?

In essence the tool is very simple - it measures the distance between point pairs and constructs shift and inset values for the poly bevel command in modo. Before it can do that effectively, however, it needs some input from you - specifically, the up (shift) direction that you're capturing the points in and the correct point order i.e. you must select the points in the order of the bevel from first to last.

The tool has a couple of options for you to specify that direction - orthogonal or polygon normal. Orthogonal requires that you tell it whether the shift of the points is along X, Y or Z (+/-).

Normal lets you pick a polygon whose normal direction defines the up direction of the bevel shape. Using Normal means you can pick a set of points going in *any* direction and provided you have a poly selected that defines the shift direction, you can grab the shape. Normal is much more versatile but requires a poly selection whereas orthogonal requires that your shift direction is along one of the primary axes but doesn't require a poly selection. Normal mode does not require that the poly is anywhere near your geometry - it is simply used to define a direction i.e. the poly normal.

Similarly, if you draw a cross section of the bevel with the vertex tool, say, it does not need to be anywhere near your geometry. In fact the point selection can be anywhere - the script finds the first point and then works out the rest from there.

Corner -v- Cross Section

There's another option that's really important but potentially confusing. You can grab a bevel shape directly from a bevel corner or the cross section of a bevel (profile). The examples below show the difference. Depending on your circumstances it might be easier to pick one or the other - the resulting inset length of the bevel shape is different: the corner option does a wee bit more calculating to find the original inset values that would give you that corner shape.

Drawing a Cross Section

If you want to draw your bevel profile/cross section, then it's simply a case of drawing the shape you require using either the vertex or pen tools (or even freezing a curve you've drawn), using Grab Cross Section and picking either a poly or axis which defines the shift direction. Always make sure your point selection is from first to last. (In the example below the vertex tool has been used to draw the points and by default they will be in the correct order. Using Grab Cross Section Y+ would be enough to grab the shape).

For greater accuracy, you can combine modo's default shapes - circles, squares etc. and then select relevant points to construct your bevel shape.

It's important to note that you can draw your cross section at any angle anywhere provided you have a poly selection whose normal defines the shift direction of the captured points. It doesn't need to be drawn next to the actual geometry you're intending to bevel - often, however, it helps to draw the shape in context so that you can get a feel for how it will look.

There Has to be a Catch

There is one 'gotcha' with the calculations I use to derive the bevel shape from your point selection - the script has no idea if you mean an outward or inward bevel. In most cases it will guess correctly, but sometimes you'll need to flip the bevel shape using the 'Flip Insets' button.

Using Flip Insets is a useful way to reverse a bevel profile in order to create a new preset (even if the original 'grab' was correct). Flip Shifts performs a similar function on the shift direction.

With both Flip Insets and Flip Shifts, the operation is applied to the stored data for the grabbed points - you won't miraculously see your bevel flip - you need to undo, Flip Insets and then use again.

How to Install PolyBevel Grabber with the Form

There are currently two components to PolyBevel Grabber - the script itself, and a configuration file to set up the form. (If you intend to use PolyBevel_Grabber in conjunction with PolyBevel_Presets then you need to follow the instructions for the latter as well - it would make sense in that case to keep all of the relevant files in a seperate, discrete directory).

PolyBevel_Grabber.pl - the perl script itself
pb_grabber.cfg - the file that creates the form.

Option 1
The way the form is configured at the moment means that if you place it directly into your modo resrc folder (on OSX you'll need to open the modo package contents and place it in the Resources folder), the form will become available to you next time you launch the application. This relies on modo's default behaviour but can result in a very cluttered resrc directory (especially if you're leeching a lot of cool stuff from Vertex Monkey). If you then place the script itself in the same directory as modo.app/modo.exe it will be available to the form without any further alterations being required.

Option 2
Alternatively, you can create your own location to store both the script and config file but will need to adjust the path locations in the pb_grabber.cfg file. The benefit of this approach is that you have control over where you keep your external files and they won't get overwritten should you update modo.

It doesn't really matter where you put them so long as you make sure you have correct paths in the relevant files.

Once you've chosen a location for both files then you need to open up the pb_grabber.cfg file in a text editor and put in the relevant path to the actual script using search and replace so that every time the script is called it has the correct path. Here's an example of how a single entry should look (but, remember, every entry for the script should be changed to the correct path using a single search and replace).

On a Mac:

<list type="Control" val="cmd @{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} norm">
<atom type="Label">Poly Normal</atom>
<atom type="Hash">54409416674:control</atom>
</list>

On a PC:

<list type="Control" val="cmd @{C:\Directory with Spaces\subdirectory\PolyBevel_Grabber.pl} norm">
<atom type="Label">Poly Normal</atom>
<atom type="Hash">54409416674:control</atom>
</list>

If the path has a space in it then the script needs to enclosed in curly brackets e.g.

@{/Users/julianjo/folder with spaces/PolyBevel_Presets.pl}

It's easy to mistakenly delete a quote mark or a space, so make sure you find and replace just the path.

Once you've configured the path in the config file you're nearly ready to roll. Fire up modo, go to File:Config Import and import the pb_grabber.cfg file you've just amended. This tells modo to load that file (i.e. the menu for PolyBevel Grabber), every time you launch modo.

For ease of access to the form simply assign the form to a key.

When The Script Runs I Get Bombarded With an Error Message

The 'General Failure' message is a known issue with modo and can be easily fixed.

Luxology themselves have released a patch for this error message on Vertex Monkey:

http://www.vertexmonkey.com/scripts_bugfix.php

Alternatively, you can just set the 'In the future' drop down to let modo know you don't want to see this message again. The error sounds dramatic but isn't, it's totally inconsequential. Luxology's bugfix script does simply that - it turns off that specific error message.

Adding the shape to Poly Bevel Presets v1.5

The script originally started as an easier way for me to populate presets for my PolyBevel_Presets script but gradually took on a life of its own. Using PolyBevel_Grabber you can send presets directly to PolyBevel_Presets. The script will locate the PolyBevel_Beveldata.txt file and either append the preset or overwrite an existing one depending on the number you choose. If, for example, you don't like the current Convex preset (or you'd like to create a higher/lower res version) then choose Add to PB Presets type in the bevel number when the requester pops up (you dont' have to include the 'b'):

..and choose to overwrite if you really want to:

If the number is not already used, the new preset will be appended to the existing list.

Using Immediately with PolyBevel Presets v1.5

So that you can store several 'grabbed' bevels in one session and use them immediately within PolyBevel_Presets, I've created a new 'Temp' area within the PolyBevel_Presets form. At the bottom of the shot below you'll see a pull down menu which lets you select the temporary bevels. This works if you store newly captured bevels in the slots that have been pre-entered into the temp buttons.

In the form below, for example, the temp buttons call b900, b901, b902 and b903. These do not exist as presets in the PolyBevel_Beveldata.txt file by default - they're just empty slots. If you capture a bevel profile and then store it using one of these numbers then it will automatically become available to you.

There's nothing to stop you creating an unlimited number of temporary slots yourself and using any numbers you wish provided the slot in the form calls a bevel number you store. At some point, however, you may need to decide whether you want to rename or remove temporary presets and 'promote' them to the main panel or create a new 'personal' form.

Arguments

The script can be used without the form. You can use most of the functionality of the script directly in the command line or if you use it mapped to various keys. For that purpose, here is a list of the arguments and how to use them:

x+, x-, y+, y-, z+, z-,
Use one of these arguments to specify to the script that the 'shift' direction of the points is along one of these axes. By default the script will assume you are 'grabbing' a cross section of a bevel.

Example:
@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} y+

Will grab a cross section of points whose shift is along Y+.

norm
Use norm to specify that you have selected a single polygon whose normal defines the direction of the shift

Example:
@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} norm

Will grab a cross section of points whose shift points in the same direction as the normal of a single polygon you have selected.

corner
Use corner to specify that you want the script to grab a 'corner' set of points and calculate back to the original bevel insets and shifts.

Example:
@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} y+ corner

flipinsets, flipshifts
Use either flipinsets or fipshifts to flip either the insets or shifts of the captured bevel.

Example:
@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} flipinsets

Will flip the insets of your captured bevel.

use
Apply the poly bevel script. It's very important to note that you must specify a scale value before use in the argument e.g. .25 use or 1 use.

Example:
@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} .25 use

Will use the captured bevel at .25 scale. It is essential that you put the scale factor in the first argument slot.

groupon, groupoff
These are used in conjunction with use and allow you to specify whether you want a group bevel or not

Example:
@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} .25 use groupon

Will use the captured bevel at .25 scale with group bevel on.

polybevel
Write the captured bevel data to the Poly Bevel Presets datafile at the scale you captured it at.

Example:
@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} polybevel

polybevelscale
Write the captured bevel data to the Poly Bevel Presets datafile at a scale you specify in argument slot one.

Example:
@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} .25 polybevelscale

Will write the captured bevel to the PolyBevel_Beveldata.txt file at .25 scale

macro
Write the captured bevel data to a macro at the scale you captured it at.

Example:
@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} macro

Will create a macro at the captured size.

macroscale
Write the captured bevel data to a macro at a scale you specify in argument slot one.

Example:
@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} .25 macroscale

Will create a macro at a quarter of its original size.

usgroup, usscale,
These arguments are important but are only for use with forms and tell the script to look in the group and scale fields in the forms (instead of looking in argument slot one) for the scale and group values.

Example:
@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} use usscale usgroup

Will use the captured bevel with the scale and group settings set in the relevant fields.

Example:
@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} polybevelscale usscale

Will save the captured bevel to the PolyBevel_Beveldata.txt file at the scale you specified in the scale field.

Argument Combinations

You can, in fact, use combinations of arguments to do several steps at once. Here's a few examples:

@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} .25 use groupon flipinsets

Will use the stored bevel at .25 scale with groupon and will flip the insets.

@{/Users/julianjo/Desktop/current pbs/PolyBevel_Grabber.pl} norm use

Will capture the shape first and then apply it immediately if you have a poly selected.

Problems and Infrequently Asked Questions

After I overwrite some of my bevels the Polybevel_Beveldata.txt file becomes unsorted

Almost. When you overwrite a bevel preset the whole data file is read into my script, the old bevel is swapped for the new one and the file is reconstructed and saved. During this process I don't bother going to elaborate lengths to sort the resulting file although each bevel/inset pair is together the sort order follows ASCII standards where 1 is followed by 10. Sorry. If I can figure out a simple fix, I'll implement. It doesn't have any impact on the functionality of the script.

The file requesters seem a little funny

Yep. If you're writing to a macro and/or you're writing a preset to PolyBevel Presets then an open/save dialog will appear. In order to use this functionality in modo, I've had to split up the name and the path which makes the process a little clunky. For example, when you write a macro you have to specify the name of the macro in one dialog box and then choose the path to which it is saved. A similar process is involved when you have to locate the PolyBevel_Beveldata.txt file if you've moved it (although in this case the requester is looking for the path to the file). You never get a requester which directly lets you select a file. It's always a path. Sorry if that's a bit confusing but, at the moment, I can't figure out a cleaner way within modo's command/script structure. There may well be one.

I've changed my paths in my Form e.g. pb_grabber.cfg but they're not reflected in modo

Classic. One of the things to look out for if you use Config:Import to keep your custom menus seperate is that if you modify an external form within modo (e.g. you go into Form Editor and change a command or name within the form) the whole form is imported into the modo.cfg (com.luxology.modo on OSX) file and takes precedence over the external form because of the way the XML hierarchy works. Any changes you make to the external imported .cfg file will, from then on, be ignored totally. So, if you change your paths in the external form you'll find that won't be reflected in modo itself. You'll either need to cut the new form entry out of the modo.cfg file and paste it over the old form in the external file or adjust the file paths directly using Form Editor or within modo.cfg itself. Don't be surprised, if you've made many edits to a form over a period of time, to find that there are multiple versions of your form in the modo.cfg file - the very last one will always take precedence (and a new one seems to get created for every edit session).

Why does the form take so long to appear?

You're on a relatively old machine, right? There's some preprocessing that modo does to forms that call scripts that can really bog down slower machines. The alternative is to call the script from a macro (as I have done for PolyBevel_Presets) but that adds another layer of complexity and most users, I would guess, have significantly faster machines than my old, but trusty Mac DP800. If you have a speed issue, please contact me and I'll set up a form that calls a macro, that, in turn, calls the script.

Notes on the Overall Structure of This Script

The script uses a combination of dot product and cross product functions to find out the shape of the bevel profile. The problem with this approach, as already mentioned, is that the script cannot really detect which way the bevel goes - in or out. There may well be a better way to guess the direction from the point selection, but at the moment, I can't figure that one out without asking the user for yet another input.

Although the 'intent' of the script is simple, it turned out to be quite complicated to realise and I'm still not sure whether it is using the correct structure. There's a considerable amount of writing to external files, overwriting external files and passing of data to the user.value 'containers' directly in the modo config. As such there are lots of dependencies - what happens if a user moves the bevel data file? What's the difference between writing files to a Mac and a PC? Why does the bevel data file only seem to work correctly with Unix line endings on OSX etc.? I've tried to test for every situation on both a Mac and a PC but I'm sure there will be areas where the script breaks because of a user input I didn't predict.

16th July 2005

Julian Johnson
julian@exch.demon.co.uk