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 adjust the parameters for the generated pattern. If you do only minor changes, like adjusting the colour of items, the preview will automatically update as soon you update a value. When your changes require a recalculation, there is a prompt displayed in the preview area and you need to click on the “Generate Pattern” button to see the effect of your changes.

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 file using the entries in the “File” menu. To start from scratch, use the “New” entry from the “File” menu.

Main Page

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

  • Generator: The generator defines the base algorithm for the artwork that is created. At the moment, there is only the “Point Grid” generator available.
  • Algorithm: This setting selects the algorithm of the generator that is used. Bets you experiment with this setting to understand the results. In oder to understand the algorithm, set “Random” to zero.
    • Largest Space First – This is the classic algorithm, where the items are placed in order of the largest free space found in the canvas.
    • From Outside to Inside – Starts placing the items at the edges of the canvas first.
    • Closest to Center – Starts at the center, then progress to the edges of the canvas.
    • Left to Right – Starts placing items at the left side, then progressing to the right side of the canvas.
    • Top to Bottom – Starts placing items at the top, then progressing towards the bottom.
    • Diagonal – Starts at the top-left edge and progressing towards the bottom-right edge.
  • 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.
  • Random placement: This controls how far an item is placed from the ideal point chosen by the algorithm. If you set this to zero, the pattern is built consistently only based on the algorithm.
  • 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.
  • Snap to Frame: If enabled, items that are close to the frame are aligned to it. This alignment is done while placing the items, therefore the space created by the minimal movement is utilised by the following items.

Canvas Page

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

At the top of the canvas page, you see a preview of its shape. This preview is automatically adjusted when you change the parameters below.

  • Frame Shape: Here you can select the overall shape of the canvas.
  • 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.
  • Canvas Background: Select a colour for the background of the canvas. The “eye” button toggles if the canvas background is visible or not. In the center you see a preview of the colour and with the two small buttons on the right side you can select the colour for the background.
  • Frame Background: That is like “Canvas Background”, just for the frame.
  • Frame Ratio: The frame shapes support a range of “ratios”. The ellipse, for example, changes from a circle to an ellipse. The triangle features various different orientation using this parameter.

The canvas and frame backgrounds 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.

Colour Page

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

At the top of this page you see a preview of the chosen colour how it is applied to the canvas with the items. With the buttons in the top-right corner, you can reset the colour to either a static colour or using the “parent” colour. For the global colour in this page there is no “parent” colour.

Under the preview, you can set dynamic values for the hue, saturation, value and the alpha level. 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 and number of items that are placed in the canvas.

  • 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 “parent” 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.
  • Duplicate: Duplicates an item.
  • 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.

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.

Input

A dynamic value works by using an input source that is transformed using a range and offset. The selected icon in the “Input” box selects this input value. The following list contains the meaning of all icons in the shown order.

  • Parent: When this is selected, the parent value is used if there is one available. E.g. for the colour hue, you can use the parent value for individual items and define an offset from it. If you change the global colour, all items will follow along.
  • Zero: It uses zero as base value, therefore the given offset sets a fixed value for the parameter.
  • Depend on X/Y Position: The value depends on the X or Y position of the item.
  • Angle to Center: The value depends on the angle to the selected centre point. Click the center box on the right side to set the desired center point.
  • Distance from Center: The value depends on the distance from the selected centre point. Click the center box on the right side to set the desired center point.
  • Random: Uses a random input value.

Range Start and End

With “Start” and “End”, you configure a range of values for most inputs. E.g. for the depend on X input the start-value defines the value at the very left side, while the end-value defines the value at the right side of the canvas.

The start can be larger than the end, in this case it reverses the direction of the values.

Offset

The offset is applied at the end to the

Center Box

By clicking on the box in the top-right corner, you open the dialog where you can select the center point.

It defines the centre for the “Angle to Center” and “Distance from Center”. The centre is defined with relative values from 0.0 to 1.0, where 0.5 is the middle of the canvas. Press shift or ctrl/cmd while moving the point to snap the locations to the grids.

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 Pattern” button starts the generator. The status of the process is displayed in the status area.

Preview Area

The preview area shows the last generated pattern. The displayed pattern is the one that gets exported to disk. If property changes require a new calculation, you will see a prompt like “The preview is out of data…” in this area.

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.