Manual – Circle Pattern Generator

This is the manual for the Circle Pattern Generator.

Main Window

After the start, the main window is displayed. Depending on your operating system and the light or dark mode on macOS, the user interface may look different. Yet, the described functionality is the same.

The window has five separate areas: Settings, Export, Actions, Preview and Status. The settings area consists of multiple pages. You can switch between the pages by clicking the tabs on top of this area or using the keyboard shortcuts in the menu.

Settings

In the settings area, you prepare the generated pattern. Changes in the values in this area have no direct effect on the preview or export, and these settings are only used when you click the “Generate” button.

If you close the application, all settings are stored and get restored at the next start. Also, you can save and load the settings into a JSON file using the “Load Values…” and “Save Values…” entries in the “File” menu.

To start from scratch, use the “Reset Settings…” entry from the “File” menu.

Main Page

All primary settings controlling the generator are on the main page.

  • Generator: Select the generator with this control. There are two generators: Rectangle and Round. The rectangle generator distributes the items in a rectangle area, and the round generator distributes them in an ellipse area.
  • Precision: The precision controls how many points are calculated to distribute the items. If you use a lot of small items, you can increase the precision to fill even the smallest gaps. If you like to create larger documents, you can lower the precision to 1mm. A higher precision uses more memory and time to generate the document.
  • Spacing: This is the required spacing, in mm, between the items. The spacing is calculated using the radius of the item, not its actual shape. With zero spacing, circles can touch each other at their circumferences.
  • Overlapping: With the overlapping value, you control how many mm is added to the radius of every item after placing them on the canvas.
  • Default Shape: Select the default shape using this control. Every item in the item list with no shape set (“default”) uses this setting for its shape.
  • Randomize positions: If you enable this option, the item positions are randomized. If this option is disabled, the generator distributes all items in an ideal, uniform way.
  • Round positions: If randomized positions are enabled, you can round the resulting positions to the selected precision. This option simplifies post-processing but can have unwanted side effects with low precision.

Canvas Page

On the canvas page, all the settings control the generated document’s size, colour and properties.

  • Size: The two values define the canvas with height in mm. The tool is not made for huge canvas sizes, better work small and scale the resulting SVG up to your desired size.
  • Margin: This value defines the margin around the canvas in mm. Items are placed inside a frame in the canvas, surrounded by this margin. You can set this margin to zero if the items are distributed up to the edge of the canvas.
  • Background Color: Select a colour for the background of the canvas. With the buttons on the right side, you can select either a colour from a list of presets or use the colour dialogue of the operating system to select a custom colour.
  • Create a Background: If this option is enabled, a solid colour background is created for the document.
  • Frame Color: Select a colour for the frame behind the items. With the buttons on the right side, you can select either a colour from a list of presets or use the colour dialogue of the operating system to select a custom colour.
  • Create a Frame: If this option is enabled, a solid colour frame is created behind the items.

The background and frame are optional. If you remove both, the resulting document has a transparent background.

Rotation Page

The rotation page controls the rotation of the items.

The rotation is applied to the items using a dynamic value. See the section “Dynamic Values” for all details.

  • Mode: You control how rotation is applied to the items with the mode setting.
  • Offset: This is the offset angle.
  • Start/End: The start and end angle for the given mode.
  • Center: The normal centre for the given mode.

Colour Page

The colour page controls how colour is applied to the individual items.

In the top row of this page, you choose if you like to apply static colours, using the “Static” (or “Default”) setting of “Dynamic” if you like to apply dynamic colours depending on the item position. With the two buttons on the right side, you can select a static colour from a list of presets or use the operating system colour dialogue to select a custom static colour.

In dynamic mode, you can set dynamic values for the hue, saturation, value and alpha level of colour. See the section “Dynamic Values” for all details.

  • Hue: The hue of a colour is specified as an angle. By changing this value, you can cycle through all rainbow colours.
  • Saturation: The saturation controls how strong a colour is. At zero per cent, no colour is there, and you get a grey. At 100%, you will get the most intense colour.
  • Value: The “value” controls the brightness of a colour. At zero per cent, the colour is black. At 100%, the colour is the brightest.
  • Alpha: With this last tab, you can also control the transparency of the items. At zero per cent, the item is fully transparent and at 100%, it is opaque.

Items Page

On the item page, you configure a list of items distributed on the canvas.

Each entry in this list configures; The shape of the item, the radius (not diameter!), The maximum number of items placed and optional custom colour for these items.

  • Shape: In this column, “default” means using the main page’s default shape. If a shape is set, it will overwrite the default.
  • Radius: The radius column contains the radius in mm for the items.
  • Count: In this column, the maximum number of placed items of this type is shown.
  • Colour: Either “default” means to use the colour defined in the “Colour” tab, or you see a preview of a custom set colour.

You get a context menu with several quick actions and property changes by right-clicking on the list. You can change the shape, radius, count, and colour in this menu. Also, you can remove and duplicate entries.

By double-clicking a row, you quickly open the editor.

Directly below the list, there is a row of action buttons:

  • Add: A click on this button opens a dialogue to add a new item to the list.
  • Edit: To edit the selected row, click on this button. Alternatively, double-click on the row. An editor dialogue will open, where you can change all individual properties of the entry.
  • Remove: A click on this button removes the selected row.
  • Sort: This action sorts the item list in the order the algorithm will use the items.
  • Copy: A click on this button will duplicate the selected row.

Item Editor

In the item editor, you can change an entry’s shape, radius, maximum count and colour.

For the colour section, you can choose “Default” to use the colour from the “Colour” tab or configure a static or dynamic colour that is only applied to items of the selected row.

By clicking on “Save Changes,” the item in the table is updated. Clicking on “Cancel” will discard all your changes.

How Items are Placed on the Canvas

Items from the item list are always placed with the largest entry first, even if this entry is at the end of the list. You can click on the “Sort” button to see the order in which the algorithm will place the items.

Items of a given size (radius) will be placed on the canvas as long there is enough space and the configured maximum number isn’t reached yet. If space is left, but the last row in the item list was reached, this space is not filled and stays empty.

Dynamic Values

Dynamic properties control a value (rotation, hue, colour saturation, colour value, colour alpha) based on the position of the placed item. Each section of a dynamic value has a mode, offset, start, end and centre setting. These settings use different units (angle, percentage) depending on the controlled value. The basic mode of operation is the same.

Mode

A dynamic value works using a selected mode. This mode controls how the value is calculated from the item position.

  • Fixed: In the fixed mode, the position does not influence the value. You can control the value using the offset.
  • Depend on X/Y Position: The value depends on the X or Y position of the item. If the position is at the left/top side of the canvas, the value from the “Start” setting is used. If the position is at the right/bottom side of the canvas, the value from the “End” setting is used. There is a soft interpolation between the “Start” and “End” values. After this interpolation, the “Offset” value is added to the result.
  • Angle to Center: The value depends on the angle to the selected centre point. The “Start” and “End” values are used to select the range of the calculated angle. “Offset” is added to this angle at the end.
  • Distance from Center: The value depends on the distance from the selected centre point. The “Start” value is at the centre and interpolates to the “End” value with a growing distance from the centre.
  • Random: In random mode, the value does not depend on the item position, but a random value between “Start” and “End” is created for each item.

Offset

After calculating the selected mode, the offset is added to the value. For fixed values, “Offset” sets this fixed value.

Start and End

With “Start” and “End”, you configure a range of values for most modes. The start can be larger than the end.

Center

This setting defines the centre for the “Angle to Center” and “Distance from Center”. The centre is defined with relative values from -1 to 1, where zero is the middle of the canvas. You can choose one of the nine default locations with the button on the right side. You can set the centre using fraction values at any point you like.

Export Area

There are two buttons and the DPI setting in the export area:

  • SVG: Use the SVG button to store the generated and currently displayed document in SVG format.
  • Bitmap: For a PNG or JPEG bitmap, click on this button. The bitmap is exported in the selected resolution. Make sure to select the desired format in the file dialogue.
  • DPI: Use this element to select the resolution of exported bitmaps.

Actions Area

A click on the “Generate” button starts the generator. The status of the process is displayed in the status area.

If the generator is supporting optimization, a click on the “Optimize Result” button tries to optimize the generated result. Optimizing means improving the distribution of the items on the canvas; as this is an iterative process, you can start optimising multiple times to get better results.

Preview Area

The preview area shows the last generated pattern. The displayed pattern is the one that gets exported to disk.

Status Area

The status area shows the current progress while generating a pattern. On the right side is a cancel button where you can stop the process anytime.

Questions, Feature Requests and Feedback

Do not hesitate to contact me if you have questions, feature requests or any feedback on the application.