HS Shape

HS Shape version 10.20 – release date 08 September 2023
=======================================================
What’s new in this version (since version 10.00, December 2022)?
10.01: Minor bug fix.
10.10: Updated for Lua 5.4 support (for Moho 14). Otherwise, there are no functional changes from 10.00
10.11-10.14: Minor bug fixes.
10.20: New subtool: Mosaic
This version will run on Moho 12 or later.

================================================


This set of tools is based on the SHAPE tools that come with Moho.
Auto-fill and auto-stroke work as expected.
In general, the Shift and Alt keys work as the standard Shape tool. Exceptions are noted below.


Inputs
======
There is an “additional functions” button (to the left of the sub-tool buttons). This changes the behaviour of the sub-tool selection buttons.
Clicking (or alt-clicking) the button cycles forwards (or backwards) through the options:
>>>  O – normal operation of the sub-tool
>>>  R – reset the sub-tool’s options (and leave the sub-tool active)
>>>  ? – print the sub-tool “help/about” message (and leave the sub-tool active)


There are 3 numerical entry fields in the menu bar: two integers and one floating point. The data entered is context sensitive depending on the tool selected. Values are preserved across invocations of each sub-tool.
Values set outside limits are reset without any error message.
Note that where the choice of input values will result in a large number of shapes being created (e.g., a square grid with 48*48 cells) the elapsed time taken to create all these shapes will be high. (Where the potential for large numbers of individual shapes exists, shapes are created on mouse up and not on mouse down.)
There is a check-box to force all drawing on frame 0 (as is the approach in Moho 13.5.3 and later). If this is not checked, the shape is created or modified on the active frame.
There is also an options button that is context dependent to allow further options depending on the active sub-tool.

Editing a shape
================
Having drawn a shape using a sub-tool it is possible to change the detail of the shape by, optionally, changing a numeric input field (other than those that directly or indirectly define the number of points in the shape) and then holding down the control key and simultaneously clicking and dragging the mouse. Once the edit operation is in progress the control key may be released if its shape modifying action is not required. Note that the shift and alt keys remain set as they were when the shape was created.
Also, where the sub-tool uses the floating point input to control scale / ratio / roundness (etc) this value can be modified immediately after the shape has been drawn to change the drawn shape.
If a shape is created on frame 0 (e.g. with the “create on frame 0” checkbox checked) then modified on a different frame (with the “create on frame 0” checkbox unchecked) the shape will be animated.


SUB-TOOLS SUMMARY
=====================
Circle Sector Oval Round Cornered Rectangle
Bone Influence Shape Annulus Concentric Polygons
Polygon Tri/Quad Mesh Right-angled triangle
Star Swiss Cross
Multi-point line Sine Parabola
Rectangular Grid Triangular Grid Mosaic
Card Suit Shapes


TOOL DESCRIPTIONS
==================

CIRCLE SECTOR
This tool creates a sector of a circle. Dragging the mouse creates a sector of up (but excluding) a full circle. Ctrl constrains to a semi-circle. Shift constrains the sector to quadrant or semi-circle; Alt moves the initial radius from vertical to horizontal.
One data entry field is enabled:  this is the number of points and is constrained to be between 4 and 72 inclusive.

OVAL
Generates an ellipse. Ctrl forces the point curvatures to “circular” (otherwise the curvature is set to give the correct ellipsoidal shape – from a straight line where one dimension is very small to near circular). Shift distributes the points equidistant from the centre. Ctrl-Shift together create a circle.
One data entry field is enabled:  this is the number of points and is constrained to be between 4 and 72 inclusive. If the number of points chosen is not divisible by 4 the input is reduced to the nearest lower multiple of 4.

ROUND CORNERED RECTANGLE
One data entry field is enabled: the radius of the semicircle that forms the corner as a ratio of the length of the smallest side. It is constrained to be between 0.01 and 0.4.
There is a checkbox to make the corners smoother (additional points are created).

BONE INFLUENCE SHAPE
This is similar to a round cornered rectangle but has semicircles on the short edge.
The style of creation can be selected by a button which, when pressed, cycles through the options:
>> use a bounding box created by the mouse click-drag to define the shape. The shape will be aligned horizontally or vertically and the dimensions will be set from the bounding box
>> use the mouse drag to define the vector along which the shape is created. In this case the “radius of the end semicircle” needs to be manually entered.

ANNULUS
Creates a single shape composed of two concentric ovals. Shift creates concentric circles.
One data entry field is enabled:  the ratio of the width of the centre to outer radius; it is constrained to be between 0.001 and 0.9950 inclusive. (A large number creates a large hole in the centre)

CONCENTRIC POLYGONS
Creates concentric polygons: each is a separate shape with the largest at the bottom of the stack. Control makes the points rounded (default is peaked).
Two data entry fields are enabled:  the number of sides on each polygon which can be between 3 and 24 inclusive and the number of concentric shapes which can be between 1 and 24 inclusive.

POLYGON
One data entry field is enabled: the number of sides which can be between 3 and 24 inclusive.

TRI/QUAD WARP MESH
Two data entry fields are enabled: the number of spokes on the “web” which can be between This can be between 3 and 48 inclusive; and the number of concentric rings which can be between 1 and 24 inclusive. The innermost polygon is subdivided into triangles; each successive outer polygon is made up of quadrilaterals.

RIGHT ANGLED TRIANGLE
This generates a right angled triangle. No data entry fields are enabled.

STAR
Creates a Star with the chosen number of arms. Ctrl makes the points rounded (otherwise they are sharp).
Two data entry fields are enabled:  these are the number of arms on the star and the ratio of the width of the centre to total radius of the star. The star can have between 3 and 72 arms inclusive; the centre ratio can be between 0.001 and 0.9950 inclusive.

SWISS CROSS
Creates a Swiss Cross. Ctrl makes the points rounded (otherwise they are right angles).
One data entry field is enabled: width of the arm of the cross as a ratio of the shortest side. This can be between 0.01 and 0.99 inclusive.

MULTI-POINT LINE
There are two main modes of operation:
>> Generate one straight line with points evenly spaced along it.
>> Generate several lines.
Shift key makes the line horizontal or, with the Alt key also pressed, Vertical. Control makes the points rounded otherwise they are peaked.
Two data entry fields are always enabled:
>> the number of points on each line – this constrained to be between 2 and 72 inclusive.
>> how many lines to draw
If more than one line is to be drawn, there is a button that cycles through the options of which there are two:
>> create multiple parallel lines – in which case the spacing may be set manually or, by checking the “base on stroke width” box the spacing is set automatically to bring the lines close together so that a standard brush will fill the gap. This automatic setting may be further manually adjusted.
>> create radial lines – in which case one data entry field is enabled – this defines the distance from the origin to the innermost points as a ratio of the line length and this is constrained to be between 0 and .990. Note that if this option is set to be very small, there will be multiple points created at the same (or very close) location and it may prove difficult to select the origin point for a specific line.

SINE
Sine wave generates a curve drawn with the number of points to create the selected number of half-cycles and with a peak-to-peak amplitude as set by the scale factor. Dragging the “end” point extends the curve from zero to the selected number of cycles until the whole curve has been generated and then it stretches the curve. The Control key constrains the curve so that fewer cycles are drawn if there are insufficient points to keep the curve properly shaped (12 points for a half-cycle). The Alt key inverts the curve. The Shift key keeps the line of zero amplitude horizontal.
Three data entry fields are enabled: the number of points in the drawn curve (6 to 144 inclusive), the maximum number of cycles 1 to 12) and the peak-to-peak size of the curve (amplitude) relative to the default frame size (0.001 to 10 inclusive).

PARABOLA
This generates a parabolic line with points evenly spaced along its x axis. Shift key aligns the end points of the line horizontally. The apex of the curve is, by default, in the same quadrant as the end point, but with the Alt key pressed the apex of the curve is inverted. Control makes the points peaked otherwise they are rounded.
Two data entry fields are enabled:  the number of points, which is constrained to be between 3 and 72 inclusive and curvature (0.001 to 10 inclusive) – a smaller number makes a flatter curve.

GRID
Creates a grid of the chosen number of rows and columns.
Two data entry fields are enabled:  these are the number of rows and columns. Both are constrained to be between 1 and 48 inclusive.
There is an options button to select the type of fill. Clicking on the button cycles through the options. There are two options:
>> create just one shape for the grid lines and one for the background fill (if the relevant autostroke / autofill options are set)
>> create separate shapes for each cell

GRID OF TRIANGLES
The options button is used to select the style of the grid of triangles. Clicking on the button cycles through the options. There are three grid variants:
>> a grid based on hexagons - two data entry fields are enabled:  these are the number of rows and the number of triangles per row. The number of rows is constrained to be between 1 and 48 inclusive; the number of triangles per row is constrained to be between 2 and 48 inclusive. This produces a “ragged edge” grid of identical triangles.
>> a grid based on squares with alternate diagonals
>> a grid based on squares with the same diagonals
In these last two options two data entry fields are enabled:  these are the number of rows and the number of squares per row. Both are constrained to be between 1 and 48 inclusive.

MOSAIC
This tool creates a Mosaic of the chosen number of rows and columns. This is different from Grid as each cell is a separate path (curve) - points are not shared.
Two data entry fields are enabled:  these are the number of rows and columns. Both are constrained to be between 1 and 24 inclusive.
The grid is created on mouse down, but the shapes have stroke / fill applied on mouse up.

CARD SUIT SHAPES
This draws a club, diamond, heart or spade.
The options button is used to select the desired shape. Clicking on the button cycles through the options.
There is one checkbox to use a fill/stroke that is usual for the suit (red fill for diamond/heart, black fill for club/spade).

For club there is a "rotundness" value which adjusts the overall shape:
-- 0 is most spread out, 10 is the most compact
For diamond, there is a "curvature" value which adjusts the straightness of the edges:
-- 0 is straight, 10 is maximum curvature.
For heart and spade there is a "roundness" which adjusts the overall shape:
-- 0 is "pointy", 10 is roundest



Installation
============

Copy (optionally rename) folder hs_shapeV10-0 to a convenient location and run the “scripts / install script” script. When prompted select the relevant folder.



Notes and known issues
======================

The “install script” process has not been tested on a mac.
There is no Localisation support.
Shapes if created with inconsistent options, exhibit “interesting” behaviours. Oval, if drawn with few points that are forced to curvature (ctrl-key), creates a bone-like shape; Star, if created with a ratio of outer:inner radius of (nearly) 1 creates a polygon; Sine if created with few points creates some crazy loops; polygons with more than about 20 sides are virtually indistinguishable from ellipses / circles.
There are no known issues; but please let me know about errors, inconsistencies, unfriendly UI, ...

Requests for changes are always welcome. Just ask. If it’s easy it’ll get done quite quickly. If it’s hard ... well, it’ll go on the list.


Next Version of this tool
=========================

Planned changes for the next release(s) are:
>>>  (over more than one release) Migrate sub-tools to be in separate .lua files
>>>  provide more support for user-written sub-tools
>>>  Additional features if/as requested
>>>  Bug fixes if/as reported or resolved