matlab-create-custom-antenna

# Custom Antenna Design Skill

You are an expert RF and antenna engineer assisting a professional engineer with custom antenna design. Use MATLAB Antenna Toolbox `customAntenna` to build arbitrary antenna structures from `shape.*` primitives, configure feeds, add substrates, and analyze performance.

## When to Use

- User wants to build a non-catalog antenna from scratch using geometric primitives
- User needs custom geometry (not available as a catalog antenna)
- User wants to import STL/CAD geometry and add feeds
- User needs 3D structures like waveguides, horns, or cavities built from shapes
- User asks about boolean operations on antenna geometry

## When NOT to Use

- User wants a standard catalog antenna (dipole, patch, horn, etc.) — use `matlab-design-antenna`
- User wants a PCB antenna with stackup layers — use `matlab-designing-pcb-antennas`
- User wants to optimize antenna parameters — use `matlab-optimizing-antennas`

## Core Workflow

1. **Build shapes** -- Create 2D or 3D primitives from the `shape.*` namespace.
2. **Transform** -- Position shapes with `translate`, `rotate`, `scale`.
3. **Combine** -- Boolean operations: `+` (union), `-` (subtraction), `&` (intersection).
4. **Modify 3D structures** -- `removeFaces` for openings, `imprintShape` for feed contact.
5. **Extrude** -- `extrudeLinear` or `extrudeRotate` to convert 2D into 3D. Assign output arguments when using extrude.
6. **Add substrate** -- `addSubstrate` for dielectric regions (requires air bounding box).
7. **Create antenna** -- `customAntenna(Shape=finalShape)`.
8. **Create feed** -- `createFeed(ant, [x y z], numEdges)`.
9. **Mesh** -- `mesh(ant, MaxEdgeLength=..., MinEdgeLength=...)`.
10. **Analyze** -- `impedance`, `sparameters`, `pattern`, etc.

## shape.* vs antenna.* -- Two Different Namespaces

**This is the #1 source of confusion.** MATLAB has two shape namespaces:

| Namespace | Used With | Examples |
|-----------|----------|---------|
| `shape.*` | `customAntenna` | `shape.Rectangle`, `shape.Box`, `shape.Cylinder` |
| `antenna.*` | `pcbStack` | `antenna.Rectangle`, `antenna.Circle`, `antenna.Polygon` |

They are **not interchangeable**. `customAntenna` requires `shape.*` objects. `pcbStack` requires `antenna.*` objects.

## 2D Shape Primitives

All 2D shapes live in the XY plane (z = 0). They can be used directly as flat metal structures or extruded into 3D.

| Shape | Key Properties |
|-------|---------------|
| `shape.Rectangle` | `Length`, `Width`, `Center`, `NumPoints`, `Metal` |
| `shape.Circle` | `Radius`, `Center`, `NumPoints`, `Metal` |
| `shape.Ellipse` | `MajorAxis`, `MinorAxis`, `Center`, `Metal` |
| `shape.Polygon` | `Vertices` (N-by-3, z must be 0), `Metal` |

```matlab
r = shape.Rectangle(Length=0.05, Width=0.03);
c = shape.Circle(Radius=0.02, Center=[0.04, 0]);
p = shape.Polygon(Vertices=[0 0 0; 0.03 0 0; 0.015 0.04 0]);
```

All shapes default to `Metal="PEC"`. Set `Metal="Copper"` for realistic conductor loss.

Available metals: `PEC`, `Copper`, `Aluminium`, `Gold`, `Silver`, `Zinc`, `Tungsten`, `Lead`, `Iron`, `Steel`, `Brass`.

## 3D Shape Primitives

| Shape | Key Properties | Notes |
|-------|---------------|-------|
| `shape.Box` | `Length`, `Width`, `Height`, `Center` | Closed box (6 faces) |
| `shape.OpenBox` | `Length`, `Width`, `Height`, `Center` | Box with one face removed |
| `shape.Cylinder` | `Radius`, `Height`, `Center`, `Cap` | `Cap=[1 1]` = both ends closed |
| `shape.OpenCylinder` | `Radius`, `Height`, `Center` | Open-ended cylinder |
| `shape.Sphere` | `Radius`, `Center` | Full sphere |
| `shape.Custom3D` | `Vertices` (from triangulation) | Arbitrary 3D mesh |

3D shapes have both `Metal` and `Dielectric` properties:

```matlab
wg = shape.Box(Length=0.023, Width=0.010, Height=0.030, Metal="PEC");
sub = shape.Box(Length=0.06, Width=0.06, Height=1.6e-3, Dielectric="FR4");
```

## Boolean Operations

```matlab
combined = shape1 + shape2;        % union (or add(shape1, shape2))
slotted = ground - slot;           % subtraction (or subtract(ground, slot))
overlap = shape1 & shape2;         % intersection (or intersect(shape1, shape2))
```

Use `RetainShape=true` in `add`/`subtract` to preserve internal boundaries for correct meshing at junctions.

### createHole (For Slots in 2D Shapes)

For cutting holes or slots in 2D shapes, use `createHole` instead of subtraction. Subtraction (`-`) on 2D `shape.*` objects can produce geometry that fails to mesh:

```matlab
ground = shape.Rectangle(Length=0.1, Width=0.1);
slot = shape.Rectangle(Length=0.05, Width=0.003);
slottedGround = createHole(ground, slot);    % use this, not ground - slot
```

**For overlapping holes** (e.g., a cross-shaped slot), union the hole shapes first, then cut once:

```matlab
hSlot = shape.Rectangle(Length=0.05, Width=0.003);
vSlot = shape.Rectangle(Length=0.003, Width=0.05);
crossSlot = hSlot + vSlot;                    % union first
slottedGround = createHole(ground, crossSlot); % single cut
```

### Alternative: Direct Polygon Definition

When boolean operations (`createHole`, `-`) fail or produce meshing issues, define the final shape directly as a `shape.Polygon` with the target outline vertices. This avoids boolean operations entirely and is often cleaner for simple truncations, chamfers, or notches.

```matlab
% Instead of: rect - triangle (boolean subtraction)
% Define the truncated rectangle directly as a polygon:
halfL = patchL/2;
cornerClip = 0.008;

% Two opposite corners truncated (e.g., for circular polarization)
verts = [
    -halfL, -halfL, 0;
     halfL-cornerClip, -halfL, 0;
     halfL, -halfL+cornerClip, 0;
     halfL, halfL, 0;
    -halfL+cornerClip, halfL, 0;
    -halfL, halfL-cornerClip, 0];

truncatedPatch = shape.Polygon(Vertices=verts);
```

This approach is preferred when the final outline is simple to describe — fewer operations, no boolean failure modes, and explicit geometry intent.

## Transforms

```matlab
translate(shape, [dx, dy, dz]);
rotate(shape, angleDeg, [x1 y1 z1]