Lesson 28 of 44 14 minAdvanced

Local vs world: families, instances and nested placement

A family is drawn once in its own local coordinates; each instance stores a placement that maps local to world. Nested families multiply placements down the chain, and the inverse takes world points back into an object’s own coordinates.

A door family, a desk block or a light fixture type is modelled once, around its own origin, in local coordinates: the door’s hinge at (0, 0, 0), its width along local X. Every instance in the project stores only a placement, a transform from that local space to the world (project) space. A hundred doors share one geometry and keep a hundred small matrices.

Interactive

Local and world coordinates

Drag the desk’s insertion point D and the world point W, and turn the desk and the chair.

desk rotation = 30° chair rotation, inside the desk = 0°

Q, local → world
in the chair	(0.40, 0.40)
in the desk	(1.60, −0.30)
in the world	(0.54, 0.54)
W, world → local
in the world	(−0.25, 1.25)
in the desk	(1.27, 0.71)
in the chair	(0.07, 1.41)

World = DeskInWorld · ChairInDesk · local. The chair is stored once, relative to the desk, so turning the desk carries it along. Going back needs the inverses: W is at (1.27, 0.71) in desk coordinates, so it is on the desk top (the desk runs 0 to 2.4 by 0 to 1.2).

Local to world

world = Placement · local. The placement’s columns are the instance’s own X, Y and Z axes, seen in the world, plus its origin. Revit exposes this as FamilyInstance.GetTransform(), with BasisX, BasisY, BasisZ and Origin. IFC stores each element’s ObjectPlacement as an IfcLocalPlacement, a position and axes relative to another placement.

Nested placement

Placements nest. A chair inside a desk family is placed relative to the desk, the desk relative to its storey, the storey relative to the building and the building relative to the site. To get world coordinates, multiply down the chain, outermost on the left:

world = Building · Storey · Desk · Chair · local

This is why IFC placements form a chain through PlacementRelTo, and why moving a storey up by 100 mm moves everything on it without touching a single element. In the widget, turn the desk and the chair turns with it, while its position inside the desk stays the same.

NestedPlacement.cs

1M4 storey = M4.Move(0, 0, 3.6);                       // level 2, in the building2M4 desk = M4.Move(10, 4, 0) * M4.RotateZ(30);         // the desk instance, on the storey3M4 chair = M4.Move(1.2, -0.7, 0);                     // the chair, nested in the desk family4 5var seatCorner = new V3(0.4, 0.4, 0.45);              // in the chair's own coordinates6M4 chairToWorld = storey * desk * chair;7 8Console.WriteLine($"In the desk:   {chair.Point(seatCorner)}");9Console.WriteLine($"On the storey: {(desk * chair).Point(seatCorner)}");10Console.WriteLine($"In the world:  {chairToWorld.Point(seatCorner)}");11Console.WriteLine($"Chair faces    {chairToWorld.Direction(new V3(0, 1, 0))}");12 13sealed class M4                       // 4x4, column vectors: p' = M * p14{15    public readonly double[,] A = new double[4, 4];16 17    public static M4 Identity()18    {19        var m = new M4();20        for (int i = 0; i < 4; i++) m.A[i, i] = 1;21        return m;22    }23    public static M4 Move(double x, double y, double z)24    {25        var m = Identity();26        m.A[0, 3] = x; m.A[1, 3] = y; m.A[2, 3] = z;27        return m;28    }29    public static M4 Scale(double x, double y, double z)30    {31        var m = Identity();32        m.A[0, 0] = x; m.A[1, 1] = y; m.A[2, 2] = z;33        return m;34    }35    public static M4 RotateZ(double degrees)36    {37        double t = degrees * Math.PI / 180, c = Math.Cos(t), s = Math.Sin(t);38        var m = Identity();39        m.A[0, 0] = c; m.A[0, 1] = -s;40        m.A[1, 0] = s; m.A[1, 1] = c;41        return m;42    }43    public static M4 operator *(M4 p, M4 q)44    {45        var m = new M4();46        for (int i = 0; i < 4; i++)47            for (int j = 0; j < 4; j++)48                for (int k = 0; k < 4; k++) m.A[i, j] += p.A[i, k] * q.A[k, j];49        return m;50    }51    public V3 Point(V3 p) => Apply(p, 1);        // w = 1: moved52    public V3 Direction(V3 v) => Apply(v, 0);    // w = 0: only turned and scaled53    V3 Apply(V3 v, double w) => new(54        A[0, 0] * v.X + A[0, 1] * v.Y + A[0, 2] * v.Z + A[0, 3] * w,55        A[1, 0] * v.X + A[1, 1] * v.Y + A[1, 2] * v.Z + A[1, 3] * w,56        A[2, 0] * v.X + A[2, 1] * v.Y + A[2, 2] * v.Z + A[2, 3] * w);57}58 59readonly record struct V3(double X, double Y, double Z)60{61    public static V3 operator +(V3 a, V3 b) => new(a.X + b.X, a.Y + b.Y, a.Z + b.Z);62    public static V3 operator -(V3 a, V3 b) => new(a.X - b.X, a.Y - b.Y, a.Z - b.Z);63    public static V3 operator *(V3 v, double k) => new(v.X * k, v.Y * k, v.Z * k);64    public static double Dot(V3 a, V3 b) => a.X * b.X + a.Y * b.Y + a.Z * b.Z;65    public static V3 Cross(V3 a, V3 b) =>66        new(a.Y * b.Z - a.Z * b.Y, a.Z * b.X - a.X * b.Z, a.X * b.Y - a.Y * b.X);67    public double Length => Math.Sqrt(Dot(this, this));68    public V3 Normalized() => this * (1 / Length);69    static string F(double v) => Math.Abs(v) < 5e-4 ? "0" : v.ToString("0.###");70    public override string ToString() => $"({F(X)}, {F(Y)}, {F(Z)})";71}

Output

In the desk:   (1.6, -0.3, 0.45)
On the storey: (11.536, 4.54, 0.45)
In the world:  (11.536, 4.54, 4.05)
Chair faces    (-0.5, 0.866, 0)

World to local

Going the other way answers many everyday questions: is this clicked point on the desk? Which side of the wall is that pipe? Is this point inside the room’s bounding box? Bring the world point into the object’s own coordinates with the inverse placement, and the test becomes simple there, because in local coordinates the desk is just 0 ≤ x ≤ 2.4 and 0 ≤ y ≤ 1.2. For a nested object, apply the inverses in reverse order: Chair⁻¹ · Desk⁻¹ · world.

WorldToLocal.cs

1M4 desk = M4.Move(10, 4, 3.6) * M4.RotateZ(30);2M4 toDesk = RigidInverse(desk);3 4foreach (var w in new V3[] { new(11, 5, 4.35), new(9, 6, 4.35) })5{6    V3 p = toDesk.Point(w);7    bool over = p.X >= 0 && p.X <= 2.4 && p.Y >= 0 && p.Y <= 1.2;8    Console.WriteLine($"{w} is {p} in desk coordinates: {(over ? "over the desk" : "not over the desk")}");9}10 11static M4 RigidInverse(M4 m)12{13    var r = M4.Identity();14    for (int i = 0; i < 3; i++)15        for (int j = 0; j < 3; j++) r.A[i, j] = m.A[j, i];16    for (int i = 0; i < 3; i++)17        r.A[i, 3] = -(r.A[i, 0] * m.A[0, 3] + r.A[i, 1] * m.A[1, 3] + r.A[i, 2] * m.A[2, 3]);18    return r;19}20 21sealed class M4                       // 4x4, column vectors: p' = M * p22{23    public readonly double[,] A = new double[4, 4];24 25    public static M4 Identity()26    {27        var m = new M4();28        for (int i = 0; i < 4; i++) m.A[i, i] = 1;29        return m;30    }31    public static M4 Move(double x, double y, double z)32    {33        var m = Identity();34        m.A[0, 3] = x; m.A[1, 3] = y; m.A[2, 3] = z;35        return m;36    }37    public static M4 Scale(double x, double y, double z)38    {39        var m = Identity();40        m.A[0, 0] = x; m.A[1, 1] = y; m.A[2, 2] = z;41        return m;42    }43    public static M4 RotateZ(double degrees)44    {45        double t = degrees * Math.PI / 180, c = Math.Cos(t), s = Math.Sin(t);46        var m = Identity();47        m.A[0, 0] = c; m.A[0, 1] = -s;48        m.A[1, 0] = s; m.A[1, 1] = c;49        return m;50    }51    public static M4 operator *(M4 p, M4 q)52    {53        var m = new M4();54        for (int i = 0; i < 4; i++)55            for (int j = 0; j < 4; j++)56                for (int k = 0; k < 4; k++) m.A[i, j] += p.A[i, k] * q.A[k, j];57        return m;58    }59    public V3 Point(V3 p) => Apply(p, 1);        // w = 1: moved60    public V3 Direction(V3 v) => Apply(v, 0);    // w = 0: only turned and scaled61    V3 Apply(V3 v, double w) => new(62        A[0, 0] * v.X + A[0, 1] * v.Y + A[0, 2] * v.Z + A[0, 3] * w,63        A[1, 0] * v.X + A[1, 1] * v.Y + A[1, 2] * v.Z + A[1, 3] * w,64        A[2, 0] * v.X + A[2, 1] * v.Y + A[2, 2] * v.Z + A[2, 3] * w);65}66 67readonly record struct V3(double X, double Y, double Z)68{69    public static V3 operator +(V3 a, V3 b) => new(a.X + b.X, a.Y + b.Y, a.Z + b.Z);70    public static V3 operator -(V3 a, V3 b) => new(a.X - b.X, a.Y - b.Y, a.Z - b.Z);71    public static V3 operator *(V3 v, double k) => new(v.X * k, v.Y * k, v.Z * k);72    public static double Dot(V3 a, V3 b) => a.X * b.X + a.Y * b.Y + a.Z * b.Z;73    public static V3 Cross(V3 a, V3 b) =>74        new(a.Y * b.Z - a.Z * b.Y, a.Z * b.X - a.X * b.Z, a.X * b.Y - a.Y * b.X);75    public double Length => Math.Sqrt(Dot(this, this));76    public V3 Normalized() => this * (1 / Length);77    static string F(double v) => Math.Abs(v) < 5e-4 ? "0" : v.ToString("0.###");78    public override string ToString() => $"({F(X)}, {F(Y)}, {F(Z)})";79}

Output

(11, 5, 4.35) is (1.366, 0.366, 0.75) in desk coordinates: over the desk
(9, 6, 4.35) is (0.134, 2.232, 0.75) in desk coordinates: not over the desk

Quick check

A chair is nested in a desk, which is placed on a storey. Which product takes the chair’s local points to the world?

Quick check

Why are families modelled in local coordinates?

Practice

Three desks have their chair nested at (1.2, −0.7, 0) in desk coordinates. The desks are at (0, 0, 0), (5, 0, 0) and (10, 0, 0), turned 0°, 90° and 180°. Print where the chair’s seat corner, (0.4, 0.4, 0) in chair coordinates, ends up for each desk.

Show a hint

For each desk, multiply Move · RotateZ · chairInDesk, and apply it to the corner with Point.

Show the solution

Solution.cs

1M4 chairInDesk = M4.Move(1.2, -0.7, 0);2var corner = new V3(0.4, 0.4, 0);3var desks = new (V3 At, double Turn)[] { (new(0, 0, 0), 0), (new(5, 0, 0), 90), (new(10, 0, 0), 180) };4 5foreach (var (at, turn) in desks)6{7    M4 chairToWorld = M4.Move(at.X, at.Y, at.Z) * M4.RotateZ(turn) * chairInDesk;8    Console.WriteLine($"Desk at {at}, turned {turn} deg: corner at {chairToWorld.Point(corner)}");9}10 11sealed class M4                       // 4x4, column vectors: p' = M * p12{13    public readonly double[,] A = new double[4, 4];14 15    public static M4 Identity()16    {17        var m = new M4();18        for (int i = 0; i < 4; i++) m.A[i, i] = 1;19        return m;20    }21    public static M4 Move(double x, double y, double z)22    {23        var m = Identity();24        m.A[0, 3] = x; m.A[1, 3] = y; m.A[2, 3] = z;25        return m;26    }27    public static M4 Scale(double x, double y, double z)28    {29        var m = Identity();30        m.A[0, 0] = x; m.A[1, 1] = y; m.A[2, 2] = z;31        return m;32    }33    public static M4 RotateZ(double degrees)34    {35        double t = degrees * Math.PI / 180, c = Math.Cos(t), s = Math.Sin(t);36        var m = Identity();37        m.A[0, 0] = c; m.A[0, 1] = -s;38        m.A[1, 0] = s; m.A[1, 1] = c;39        return m;40    }41    public static M4 operator *(M4 p, M4 q)42    {43        var m = new M4();44        for (int i = 0; i < 4; i++)45            for (int j = 0; j < 4; j++)46                for (int k = 0; k < 4; k++) m.A[i, j] += p.A[i, k] * q.A[k, j];47        return m;48    }49    public V3 Point(V3 p) => Apply(p, 1);        // w = 1: moved50    public V3 Direction(V3 v) => Apply(v, 0);    // w = 0: only turned and scaled51    V3 Apply(V3 v, double w) => new(52        A[0, 0] * v.X + A[0, 1] * v.Y + A[0, 2] * v.Z + A[0, 3] * w,53        A[1, 0] * v.X + A[1, 1] * v.Y + A[1, 2] * v.Z + A[1, 3] * w,54        A[2, 0] * v.X + A[2, 1] * v.Y + A[2, 2] * v.Z + A[2, 3] * w);55}56 57readonly record struct V3(double X, double Y, double Z)58{59    public static V3 operator +(V3 a, V3 b) => new(a.X + b.X, a.Y + b.Y, a.Z + b.Z);60    public static V3 operator -(V3 a, V3 b) => new(a.X - b.X, a.Y - b.Y, a.Z - b.Z);61    public static V3 operator *(V3 v, double k) => new(v.X * k, v.Y * k, v.Z * k);62    public static double Dot(V3 a, V3 b) => a.X * b.X + a.Y * b.Y + a.Z * b.Z;63    public static V3 Cross(V3 a, V3 b) =>64        new(a.Y * b.Z - a.Z * b.Y, a.Z * b.X - a.X * b.Z, a.X * b.Y - a.Y * b.X);65    public double Length => Math.Sqrt(Dot(this, this));66    public V3 Normalized() => this * (1 / Length);67    static string F(double v) => Math.Abs(v) < 5e-4 ? "0" : v.ToString("0.###");68    public override string ToString() => $"({F(X)}, {F(Y)}, {F(Z)})";69}

Output

Desk at (0, 0, 0), turned 0 deg: corner at (1.6, -0.3, 0)
Desk at (5, 0, 0), turned 90 deg: corner at (5.3, 1.6, 0)
Desk at (10, 0, 0), turned 180 deg: corner at (8.4, 0.3, 0)

Remember

Families are modelled once in local coordinates; each instance stores a placement.
world = Placement · local; the placement’s columns are the instance’s axes and origin.
Nested placements multiply down the chain, outermost on the left.
The inverse placement takes world points into an object’s own coordinates, where tests are simple.
Keeping geometry local keeps its coordinates small and precise.

Foundations

Vectors

Lines and curves

Planes and polygons

Matrices and transforms

Rotations in depth

3D geometry and solids

Master level

Local vs world: families, instances and nested placement

Local and world coordinates

Local to world

Nested placement

World to local

Remember