## 2007-11-02

### Plane Geometry in Java (I)

Algebras have computational content, and the Plane Geometry Algebra I presented is no exception. It's time to put it to test by implementing a DSL embodying it. I'll use value objects to represent geometric objects in the plane. The reason for this decision, if it is not obvious enough, is that points, vectors and lines, as geometric entities, have no meaningful state.

As pointed out in C2, value objects should be immutable; this implies that there is no point in hiding the instance variables behind setters, as the values are determined at the moment of construction. On the other hand, it is necessary to ensure proper value semantics by correctly implementing `equals` and `hashCode`.

I find it easiest to start with the class `Vec`, as vectors have a very well-known, rich structure that you will probably find familiar. But first, the basic `Object` contract:

```final class Vec {
public final double i;
public final double j;

public Vec(double i, double j)   { this.i = i; this.j = j; }

public static final Vec ZERO = new Vec(0, 0);

public boolean equals(Object o) {
if (o == null || !(o instanceof Vec)) return false;
else if (this == o) return true;
final Vec that = (Vec) o;
return this.i == that.i && this.j == that.j;
}

public int hashCode() {
return (int) ((Double.doubleToLongBits(i) >> 32) & 0xffffffffL)
^ (int) ((Double.doubleToLongBits(j) >> 32) & 0xffffffffL);
}

public String toString() {
return String.format("[%g , %g]", i, j);
}
```

There is a distinguished vector, the zero vector.

In order for `equals` to be an equivalence relation, it must be closed on its domain (that is, it must compare meaningfully only `Vec`s, line 1), reflexive (line 2), symmetric and transitive. The equality operator in Java fulfills these properties, and so (line 4), using it to compare by value the coordinates ensures that the overall result conforms.

With respect to `hashCode`, there are many proposed methods to hash IEEE 754 `double`s, but most aim at "chunking" buckets of nearby values by chopping off the least significant bits of the mantissa. To avoid clustering more in one coordinate than over the other, I mix symmetrically bits from both values using an exclusive-or.

Now, let's flesh out `Vec`'s structure, not forgetting the perp operation in the Algebra:

```  public Vec add(Vec v)            { return new Vec(i + v.i, j + v.j); }
public Vec neg()                 { return new Vec(-i, -j); }
public Vec scale(double k)       { return new Vec(k * i, k * j); }
public Vec perp()                { return new Vec(-j, i); }
```

and endow it with a norm and a scalar product:

```  public double dot(Vec v)         { return i * v.i + j * v.j; }
public double norm()             { return Math.hypot(i, j); }
public double arg()              { return Math.atan2(j, i); }
public Vec unit()                { return scale(1/norm()); }
```

A natural operation on vectors is to find the enclosed (convex) angle between them. The dual operation is to rotate a vector by a given angle. It is well-known that the dot product between two plane vectors is proportional to the cosine of the comprised angle. By Theorem 16, the perp-dot product is proportional to the sine of the same angle. The cross product captures both proportionalities in vectorial form:

```  public Vec cross(Vec v)          { return new Vec(dot(v), perp().dot(v)); }
```

This operation satisfies the following properties:

```(0.0)  u × (v + w) = u × v + u × w
(0.1)  (u + v) × w = u × w + v × w
(0.2)  (k ⋅ u) × v = k ⋅ (u × v)
(0.3)  u × (k ⋅ v) = k ⋅ (u × v)
(0.4)  (-u) × v = u × (-v) = -(u × v)
(0.5)  (u × v)⊥ = u × v⊥
(0.6)  u × v = u⊥ × v⊥
(0.7)  u × v⊥ = -u⊥ × v
```

Properties (0.0) to (0.3) show that cross is linear on both arguments. This is a consequence of both the linearity of dot product and that of perp. From this, Property (0.4) is an easy consequence. Properties (0.4) to (0.7) capture the rotational invariance of the cross product, at least for quarter rotations and reflections. With this, we can define:

```  public static Vec rotor(double a) {
return new Vec(Math.cos(a), Math.sin(a));
}

public double angle(Vec v)       { return cross(v).arg(); }
public Vec rotate(double a)      { return rotor(-a).cross(this); }
}
```

That `angle` correctly captures the intended functionality is clear from the definitions:

```   u.angle(v)
= { Definition }
u.cross(v).arg()
= { Definition }
(new Vec(u.dot(v), u.perp().dot(v))).arg()
= { Properties of dot, perp-dot }
(new Vec(|u|⋅|v|⋅cos.(θ.u.v), |u|⋅|v|⋅sin.(θ.u.v)).arg()
= { Definition `arg`, `atan2` }
atan.((|u|⋅|v|⋅sin.(θ.u.v)) / (|u|⋅|v|⋅cos.(θ.u.v)))
= { Algebra, definition tan }
θ.u.v
```

Other properties of `angle` are:

```(1.0)  θ.u.v = -θ.v.u
(1.1)  θ.u.v = θ.(k⋅u).v = θ.u.(k⋅v)
(1.2)  |v|⋅u.`rotate`(θ.u.v) = |u|⋅v
(1.3)  u × (u.`rotate`(a)) = |u|²⋅`rotor`(a)
(1.4)  θ.u.(u.`rotate`(a)) = a
```

Next, I will present points.