Tarek AlGhorani Blog

BETABeta version

From Ornament to an Open Semantic Structure for Geometric Patterns — Pattern Geometry Commons

16 min read

Arabic version

I recently launched an open-source project called Pattern Geometry Commons. The project aims to build a shared, open layer for describing two-dimensional geometric patterns as systems that can be understood, validated, transformed, and reused, rather than simply as attractive drawings.

The central idea appears simple: instead of starting with the question, “How do I draw this shape?”, the project begins with a deeper one: What does this pattern mean?

Is it a repeating field? Does it have a radial arrangement? Is it based on a hexagonal or square grid? Is its primary element a star, rosette, polygon, or custom shape? Is it intended for display on the web, conversion to CAD, or fabrication with a laser or CNC machine?

This led to the project’s core idea: an intermediate layer that separates the meaning of a pattern from the way its geometry is produced.

Why This Project?

When working with geometric patterns, especially Islamic patterns, architectural ornament, abstract grids, and designs intended for fabrication, two problems commonly arise.

The first is that many tools know how to draw lines, paths, and coordinates, but they do not know what those lines represent. From their perspective, a six-pointed star, a geometric rosette, or an architectural grid is not a meaningful “pattern.” It is simply a collection of points, lines, and paths.

The second problem is that each tool keeps its logic inside itself. If you build a pattern in an SVG editor, it remains tied to the SVG approach. If you build it with Maker.js, it remains tied to Maker.js logic. If you later need it in CAD or DXF, you will often have to rethink it, convert it manually, or write new code.

Pattern Geometry Commons attempts to address this problem through an intermediate layer that can be called a Semantic Intermediate Representation, or Semantic IR for short.

The project does not begin with the final drawing. It begins with a semantic description of the pattern that includes:

  • The pattern type.
  • The family of elements within it.
  • The arrangement or grid system.
  • The symmetry mode.
  • The requested rendering method.
  • The requested output format.

Another layer, the Backend, then decides how to transform this description into SVG, Maker.js, or DXF.

What Is Pattern Geometry Commons?

Pattern Geometry Commons is an open-source JavaScript project that provides:

  1. An IR specification for describing two-dimensional geometric patterns.
  2. A JSON Schema for validating pattern files.
  3. A Validator that checks whether a geometric description conforms to the specification.
  4. A Compiler that transforms the semantic description into actual output.
  5. Backends for producing SVG, Maker.js, and DXF.
  6. A CLI for using the project from the command line.
  7. An API for programmatic use within JavaScript projects.
  8. Ready-made examples of Islamic, abstract, and fabrication-oriented patterns.
  9. An extensible architecture that allows new backends to be added later.

The project is published on GitHub under the Apache-2.0 license and is available as an npm package named:

@tarek-g/pattern-geometry-commons

What Is the Project Not Trying to Be?

It is important to define the project’s boundaries from the beginning.

This project is not a conventional geometry library that calculates every coordinate itself. It is not a complete drawing engine like a design tool, and it is not a replacement for Maker.js, SVG, or CAD.

More precisely, it is a layer that comes before all of them.

It does not say, “Draw this line from point A to point B.”

Instead, it says, “We have a repeating-field pattern based on a hexagonal grid. It contains a motif from the star family with a specified number of sides and a defined symmetry mode, and we want to output it as SVG or DXF.”

The backend then transforms that meaning into actual geometry.

This separation between meaning and drawing is the core of the project.

The Architecture: From Meaning to Form

The project’s architecture can be simplified as follows:

flowchart TD
  ir["Pattern IR<br/>Semantic pattern description"]
  validator["Validator<br/>Specification validation"]
  compiler["Compiler<br/>Conversion routing"]
  registry["Backend Registry<br/>Output converter selection"]
  svg["SVG"]
  makerJson["Maker.js JSON"]
  makerSvg["Maker.js SVG"]
  dxf["DXF"]
  custom["Custom Backend<br/>registerBackend"]

  ir --> validator --> compiler --> registry
  registry --> svg
  registry --> makerJson
  registry --> makerSvg
  registry --> dxf
  custom -. "register" .-> registry

The IR is a JSON file that describes the pattern.

The Validator checks that the file is valid and conforms to the specification.

The Compiler reads the IR and directs the process to the appropriate backend.

The Backend produces the final output: SVG for the web, Maker.js for geometric processing, or DXF for fabrication and CAD tools.

This approach prevents the pattern from being confined to a single tool. The same semantic description can produce more than one format.

Why the Word “Commons”?

The word Commons is important here.

The goal is not limited to building a tool for one project. It is to turn part of a research and production infrastructure into a shared resource that others can use and build upon.

Geometric patterns are more than ornament. They occupy a field where art, mathematics, architecture, programming, craft, digital fabrication, and visual history intersect. Yet the tools used to work with them are often closed, tied to the logic of a single application, or focused only on visual output.

This project attempts to open a deeper layer: the description layer.

If we have a shared representation for patterns, many tools could eventually be built on top of it, including:

  • Digital exhibitions that explain a pattern’s structure.
  • Customizable ornament generators.
  • Educational tools for understanding symmetry and grids.
  • Design interfaces that produce SVG or DXF.
  • Cultural archives that document patterns and their sources.
  • Digital fabrication tools based on clear, verifiable descriptions.

What Is pg-ir-v0?

The current version of the intermediate representation specification is called:

pg-ir-v0

It is the first stable version of Pattern Geometry IR within the project.

Every IR file must declare its version explicitly. Identifying the specification version makes validation and development easier and helps preserve future compatibility.

Here is a simplified example:

{
  "version": "pg-ir-v0",
  "pattern": {
    "id": "my-hex-star"
  },
  "geometry": {
    "tiling": {
      "type": "regular",
      "id": "6.6.6",
      "cellSize": 60
    },
    "motifs": [
      {
        "id": "star-1",
        "family": "star",
        "parameters": {
          "sides": 6,
          "skip": 1,
          "rotation": 0
        },
        "renderMode": "line"
      }
    ]
  }
}

This example does not describe an arbitrary shape. It defines a pattern based on a hexagonal grid, containing a motif from the star family with explicit parameters.

Core Classifications in the IR

The project supports several ways to classify patterns, including the following.

1. Pattern Type

A pattern can be, for example:

  • repeating-field: a regularly repeating field.
  • frieze: an ornamental strip or border.
  • radial: a radial arrangement around a center.
  • freeform: a free-form layout.
  • lattice: a structural lattice.

These classifications help describe the overall structure of a pattern before it is produced.

2. Motif Family

The primary element within a pattern can be:

  • star: a star.
  • rosette: a geometric rosette or flower.
  • polygon: a regular polygon.
  • simple: a simple shape such as a circle.
  • custom: a custom element defined by the backend.
  • irregular: an irregular shape.

This layer matters because a geometric pattern is understood through both its coordinates and the types of elements from which it is composed.

3. Tiling System

The project supports different arrangements, including:

  • 6.6.6: a hexagonal grid.
  • 4.4.4.4: a square grid.
  • 4.8.8: a square with two octagons.
  • 3.4.6.4: a triangle, square, hexagon, and square.
  • diagonal-grid: a diagonal grid.
  • lattice: a structural lattice.
  • none: no specified arrangement.

These values describe spatial relationships within a pattern without immediately descending into drawing details.

4. Render Mode

The IR can specify the requested rendering method, such as:

  • line: line drawing.
  • fill: filled geometry.
  • interlace: an over-and-under visual interlace.
  • band: bands.
  • none: data only, with no drawing.

This makes it possible to use the same pattern for different purposes, including visual presentation, structural study, and fabrication.

Backends: Why Do We Need More Than One Output?

One of the project’s strengths is that it does not tie a pattern to a single output.

It currently includes backends for producing:

  • SVG for display on the web and in browsers.
  • Maker.js JSON for working with a processable geometric model.
  • Maker.js SVG for users who want to use Maker.js with SVG output.
  • DXF for CAD and digital fabrication.

The Core does not handle the final coordinate details for every format. It preserves the semantics and manages validation and routing. The backend transforms that information into low-level geometry.

As a result, adding a new backend in the future does not require rebuilding the entire project. A custom backend can be registered as long as it follows a clear contract.

Here is a short programming example:

// يوضح هذا المثال كيفية تسجيل backend مخصص داخل المشروع ثم استخدامه كصيغة إخراج جديدة.
import { registerBackend, compileIr } from "@tarek-g/pattern-geometry-commons"
 
registerBackend("my-format", (ir, options) => {
  return {
    result: "custom output",
    meta: {
      format: "my-format",
      patternId: ir.pattern.id,
    },
  }
})
 
const output = await compileIr(ir, { format: "my-format" })

Using the Project from the Command Line

The package can be installed through npm:

# يثبت هذا الأمر حزمة Pattern Geometry Commons لاستخدامها داخل مشروع JavaScript.
npm install @tarek-g/pattern-geometry-commons

You can then validate an IR file:

# يتحقق هذا الأمر من أن ملف pattern.json يلتزم بمواصفة pg-ir-v0.
node scripts/validate.mjs pattern.json

You can compile it to SVG:

# يحوّل هذا الأمر ملف IR إلى SVG ويحفظ الناتج في output.svg.
node scripts/compile.mjs pattern.json --format svg --out output.svg

Or compile it to DXF for CAD or fabrication:

# يحوّل هذا الأمر ملف IR إلى DXF مناسب للتجربة داخل أدوات CAD مثل LibreCAD أو AutoCAD.
node scripts/compile.mjs pattern.json --format makerjs-dxf --out output.dxf

The project also provides test commands for checking the examples, compiler, backends, and package boundaries.

Using the Project Programmatically

The project can be used as an API within JavaScript:

// يوضح هذا المثال طريقة التحقق من IR ثم تجميعه إلى SVG داخل تطبيق JavaScript.
import { validateIr, compileIr } from "@tarek-g/pattern-geometry-commons"
 
const validation = validateIr(ir)
 
if (!validation.valid) {
  console.error(validation.errors)
} else {
  const { result, meta } = await compileIr(ir, { format: "svg" })
  console.log(result)
  console.log(meta)
}

Several public functions are available, including:

  • validateIr(ir) for validating an IR.
  • compileIr(ir, opts) for compiling to a specified format.
  • loadSchema() for loading the JSON Schema.
  • registerBackend(format, fn) for registering a custom backend.
  • listFormats() for listing available formats.
  • listExamples() for listing examples.
  • loadExample(path) for loading an example.
  • compileSvg(ir, opts) for producing SVG.
  • compileMakerJsDxf(ir, opts) for producing DXF.

Project Examples

The project includes a collection of examples divided into several categories.

Islamic Patterns

These include:

  • A six-pointed star field.
  • An eight-pointed star based on a square-and-octagon arrangement.
  • A ten-pointed star.
  • A geometric rosette within a hexagonal field.

These examples connect the project to a visually rich field: Islamic ornament and historical geometric patterns.

Abstract Patterns

Examples include:

  • A simple square grid.
  • A radial arrangement.
  • Intersecting Moiré lines.

These examples show that the project is not limited to Islamic ornament. It can also describe general visual systems.

Fabrication Patterns

Examples include:

  • A CNC perforated screen.
  • A laser-cut panel.
  • An architectural grid that can be considered in the context of water-jet fabrication or architectural façades.

This category moves the project from visual display into digital fabrication.

A Practical Example: From Semantic Description to SVG

Suppose we want to create a six-pointed star pattern.

We begin with an IR file that describes the pattern version, identity, grid, motif, and parameters. We then validate the file. If it is valid, we compile it to SVG.

The steps would look roughly like this:

# يتحقق هذا الأمر من سلامة ملف IR قبل محاولة تحويله إلى أي صيغة إخراج.
node scripts/validate.mjs my-star.json

If validation succeeds, we compile the file:

# يحوّل هذا الأمر النمط الموصوف في my-star.json إلى ملف SVG قابل للعرض في المتصفح.
node scripts/compile.mjs my-star.json --format svg --out my-star.svg

If we want to use it in CAD:

# يحوّل هذا الأمر نفس النمط إلى DXF، أي أن الوصف نفسه يمكن أن يخدم مسار تصنيع أو CAD.
node scripts/compile.mjs my-star.json --format makerjs-dxf --out my-star.dxf

The important point is that the original file has not changed. Only the backend and output have changed.

Why Does This Matter for Islamic Geometric Patterns?

Islamic geometric patterns are often presented as finished ornament. We see the image, but we do not always see the structure that produced it.

That is insufficient for research, museum, or educational work. We need to know:

  • What grid is the pattern based on?
  • What is its primary element?
  • How does it repeat?
  • How does symmetry relate to the final form?
  • Can it be produced in more than one format?
  • Can it be compared with another pattern?
  • Can it be connected to a source, tradition, or architectural use?

This project does not answer all these questions on its own, but it provides a technical layer on which such work can be built.

Instead of remaining an image, the ornament can become verifiable semantic data.

This matters for any larger project that aims to build a pattern atlas, visual archive, digital exhibition, or educational tool that explains how patterns work rather than merely displaying them.

How It Relates to My Other Projects

I do not see this project as separate from my broader interest in building digital knowledge systems.

In other projects, I work with texts, concepts, articles, people, relationships, and semantic maps. Here, I move into a visual and geometric domain, but the underlying question is similar:

How do we transform something complex into a structure that can be understood, navigated, and reused?

With texts, we may have articles, concepts, quotations, and relationships.

With geometric patterns, we have grids, symmetries, motifs, repetitions, and outputs.

In both cases, the goal extends beyond “producing content.” It involves building a layer that makes the content available for analysis, connection, and publication.

From this perspective, Pattern Geometry Commons can be understood as part of a broader interest in open knowledge systems: making complex structures, whether textual or visual, indexable, understandable, and transformable.

Why Is Separating Meaning from Output Important?

Conflating meaning with output makes projects fragile.

If a pattern is only an SVG, you have the final form, but you do not necessarily know how to regenerate, modify, or compare it.

If it is only a DXF, it may be useful for fabrication, but it is not necessarily suitable for explanation, education, or interactive display.

If the pattern is code inside a specific library, it remains tied to that library.

With a clear IR, however, you have an intermediate description that can move between tools.

This resembles what happens in compilers: there is a high-level language, then an intermediate representation, followed by multiple outputs. I am applying the same idea here to geometric patterns.

Where Can the Project Be Used?

Pattern Geometry Commons can be used in several contexts.

1. Web and Interactive Design

It can produce SVG for display in the browser and for use in interactive interfaces, digital exhibitions, educational tools, or pattern generators.

2. CAD and Fabrication

Through Maker.js and DXF, it can support workflows toward laser cutting, CNC, water-jet fabrication, or architectural models.

3. Education

The project can explain the relationship between grids, symmetry, and visual elements. Instead of seeing only the finished form, a student can see the structure behind it.

4. Cultural Archiving

Patterns could later be connected to sources, locations, images, references, or dates so that they do not remain isolated drawings.

5. Visual Research

A semantic representation makes comparison between patterns possible: Which ones use a hexagonal grid? Which rely on a radial arrangement? Which use a rosette? Which can be converted to DXF?

Limits of the Current Version

The project is still in its first stage, so it is important not to overstate its capabilities.

The current version establishes the core architecture, including:

  • An IR specification.
  • A JSON Schema.
  • Validation.
  • A Compiler.
  • Core backends.
  • Examples.
  • A CLI.
  • An API.
  • Tests.
  • An open license.

Some features are outside the current scope or require further development, including:

  • A complete visual editor.
  • An advanced style maps system.
  • Persistence for a complete workspace state.
  • PDF support as a stable backend.
  • Highly detailed modeling of every form of interlace.
  • Connections between patterns and historical or archival sources.
  • A finished user interface for non-developers.

This scope is intentional. The project begins with the solid foundational layer: specification, validation, and transformation.

What Has Actually Been Completed?

The current version includes an almost complete project structure:

  • A README file.
  • An Apache-2.0 license.
  • A NOTICE file for copyright and attribution.
  • A package.json file for the package.
  • A spec/ directory containing the JSON Schema.
  • A src/ directory containing the core code.
  • A backends/ directory containing SVG and Maker.js.
  • An examples/ directory containing multiple examples.
  • A scripts/ directory containing CLI tools.
  • Tests for the IR, compiler, backends, and package boundaries.
  • An initial release as an npm package.
  • An initial official release on GitHub.

The project is therefore more than a theoretical idea. It is a package that can be installed and tested.

Why Is This Project Important to Me?

This project brings together several strands of my work and interests.

There is an artistic dimension: patterns, ornament, and visual geometry.

There is a technical dimension: the compiler, schema, API, backends, npm, and tests.

There is a knowledge dimension: how to represent complex things in a way that allows them to be understood rather than merely consumed.

There is also an open dimension: turning personal work and research infrastructure into a resource that others can use.

I am interested in systems that make knowledge navigable, analyzable, and publishable. In this project, the knowledge is not a political text, an archive, or an article. It is a geometric pattern. The principle remains the same: seeing the output is not enough; we must understand its structure.

The Next Step

The next steps could proceed in several directions:

  • Expanding the examples of Islamic patterns.
  • Improving support for interlace and banded patterns.
  • Building a visual web demo.
  • Developing new backends.
  • Connecting patterns to sources and references.
  • Building a deeper documentation layer.
  • Opening the project to external contributions.
  • Using it as the basis for an exhibition or visual atlas of patterns.

The priority now is to make the first layer clear and stable: semantic description, validation, compilation, and multiple outputs.

Conclusion

Pattern Geometry Commons is a small but serious attempt to move geometric patterns from the level of the final image to the level of an understandable structure.

Instead of remaining a closed file or static drawing, an ornament can become a semantic description that can be validated, transformed, and built upon.

This is what I want to test: whether we can create a bridge between art, geometry, programming, and archiving that begins with the meaning behind the form rather than with the form alone.

Recent Posts