diff --git a/src/ifcviewer/Federation.cpp b/src/ifcviewer/Federation.cpp
new file mode 100644
index 0000000000..12ba3acb0f
--- /dev/null
+++ b/src/ifcviewer/Federation.cpp
@@ -0,0 +1,103 @@
+/********************************************************************************
+ * *
+ * This file is part of IfcOpenShell. *
+ * *
+ * IfcOpenShell is free software: you can redistribute it and/or modify *
+ * it under the terms of the Lesser GNU General Public License as published by *
+ * the Free Software Foundation, either version 3.0 of the License, or *
+ * (at your option) any later version. *
+ * *
+ * IfcOpenShell is distributed in the hope that it will be useful, *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
+ * Lesser GNU General Public License for more details. *
+ * *
+ * You should have received a copy of the Lesser GNU General Public License *
+ * along with this program. If not, see . *
+ * *
+ ********************************************************************************/
+
+#include "Federation.h"
+#include "Unit.h"
+
+#include
+
+namespace {
+
+constexpr double kPi = 3.14159265358979323846;
+constexpr double kDegToRad = kPi / 180.0;
+
+Eigen::Matrix4d translation4(const Eigen::Vector3d& t) {
+ Eigen::Matrix4d M = Eigen::Matrix4d::Identity();
+ M(0, 3) = t.x();
+ M(1, 3) = t.y();
+ M(2, 3) = t.z();
+ return M;
+}
+
+// Intrinsic XYZ Euler: R = R_z(z) · R_y(y) · R_x(x).
+Eigen::Matrix4d eulerXYZ(const Eigen::Vector3d& rxyz_rad) {
+ const Eigen::Matrix3d R3 =
+ (Eigen::AngleAxisd(rxyz_rad.z(), Eigen::Vector3d::UnitZ()) *
+ Eigen::AngleAxisd(rxyz_rad.y(), Eigen::Vector3d::UnitY()) *
+ Eigen::AngleAxisd(rxyz_rad.x(), Eigen::Vector3d::UnitX())).matrix();
+ Eigen::Matrix4d R = Eigen::Matrix4d::Identity();
+ R.block<3, 3>(0, 0) = R3;
+ return R;
+}
+
+} // namespace
+
+double federationUnitToMeters(const FederationConfig& cfg) {
+ return convert(1.0, cfg.unit_prefix, cfg.unit_name, "", "METRE");
+}
+
+Eigen::Matrix4d composeFederationOrigin(const FederationOrigin& origin,
+ const FederationConfig& cfg) {
+ const double u = federationUnitToMeters(cfg);
+ const Eigen::Vector3d xyz_m = origin.xyz * u;
+ const double rz_rad = origin.rz_deg * kDegToRad;
+
+ const Eigen::Matrix3d Rz =
+ Eigen::AngleAxisd(rz_rad, Eigen::Vector3d::UnitZ()).matrix();
+ Eigen::Matrix4d Rz4 = Eigen::Matrix4d::Identity();
+ Rz4.block<3, 3>(0, 0) = Rz;
+
+ return Rz4 * translation4(-xyz_m);
+}
+
+Eigen::Matrix4d composeModelTransform(const ModelTransform& xf,
+ const FederationConfig& fed_cfg,
+ const ModelUnits& model_units,
+ const Eigen::Matrix4d& stage2_meters) {
+ const double u_fed = federationUnitToMeters(fed_cfg);
+
+ Eigen::Vector3d A_m;
+ if (xf.a_frame == AFrame::ModelLocal) {
+ // a is in the model's project length unit, expressed in the
+ // pre-stage2 frame. Convert to metres, then lift through stage 2.
+ const Eigen::Vector4d a_h(
+ xf.a.x() * model_units.project_length_to_meters,
+ xf.a.y() * model_units.project_length_to_meters,
+ xf.a.z() * model_units.project_length_to_meters,
+ 1.0);
+ A_m = (stage2_meters * a_h).head<3>();
+ } else {
+ // a is in the model's map unit, expressed in the post-stage2 frame.
+ A_m = xf.a * model_units.map_unit_to_meters;
+ }
+
+ const Eigen::Vector3d B_m = xf.b * u_fed;
+ const Eigen::Vector3d pivot_m = xf.pivot * u_fed;
+
+ const Eigen::Matrix4d R_local = eulerXYZ(xf.rxyz_deg * kDegToRad);
+ const Eigen::Matrix4d R_at_pivot =
+ translation4(pivot_m) * R_local * translation4(-pivot_m);
+
+ // Translate so R_at_pivot · A lands at B.
+ const Eigen::Vector4d Ah(A_m.x(), A_m.y(), A_m.z(), 1.0);
+ const Eigen::Vector3d RA = (R_at_pivot * Ah).head<3>();
+ const Eigen::Matrix4d T = translation4(B_m - RA);
+
+ return T * R_at_pivot;
+}
diff --git a/src/ifcviewer/Federation.h b/src/ifcviewer/Federation.h
new file mode 100644
index 0000000000..885ee51ed9
--- /dev/null
+++ b/src/ifcviewer/Federation.h
@@ -0,0 +1,116 @@
+/********************************************************************************
+ * *
+ * This file is part of IfcOpenShell. *
+ * *
+ * IfcOpenShell is free software: you can redistribute it and/or modify *
+ * it under the terms of the Lesser GNU General Public License as published by *
+ * the Free Software Foundation, either version 3.0 of the License, or *
+ * (at your option) any later version. *
+ * *
+ * IfcOpenShell is distributed in the hope that it will be useful, *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
+ * Lesser GNU General Public License for more details. *
+ * *
+ * You should have received a copy of the Lesser GNU General Public License *
+ * along with this program. If not, see . *
+ * *
+ ********************************************************************************/
+
+// Federation-level transformation data model and compose helpers.
+//
+// A federation is the user's working scene, composed of one or more IFC
+// models. Each model lives at:
+//
+// stage3 · stage4 · stage2 · placement_stage1
+//
+// where:
+// - stage1 is per-mesh vertex rebasing (applied to the geometry buffers)
+// - stage2 is the per-model georef matrix (immutable, derived from the IFC)
+// - stage3 is the federation-wide false origin (mutable, this header)
+// - stage4 is the per-model placement within the federation (mutable, this header)
+//
+// All composed matrices are in metres. The user-authored intent is stored
+// in source units (model project unit / model map unit / federation unit) to
+// preserve precision; conversion to metres happens in the compose helpers.
+
+#ifndef FEDERATION_H
+#define FEDERATION_H
+
+#include
+
+#include
+
+// Federation-wide settings persisted in .ifcfed.
+struct FederationConfig {
+ // IfcSIUnit name ("METRE") or IfcConversionBasedUnit name ("foot", "inch", ...).
+ std::string unit_name = "METRE";
+ // SI prefix ("MILLI", "KILO", ...) — empty for unprefixed or for
+ // conversion-based units.
+ std::string unit_prefix = "";
+};
+
+// Stage 3 — the federation false origin. Authoring intent is "nominate this
+// XYZ as the new origin, with optional Z-axis heading rotation". Composed as
+//
+// stage3 = R_z(rz_deg) · T(-xyz_in_metres)
+//
+// i.e. translate the federation so the nominated point lands at the origin,
+// then rotate around the new origin. Translation is given in federation unit;
+// rotation is in degrees.
+struct FederationOrigin {
+ Eigen::Vector3d xyz = Eigen::Vector3d::Zero(); // federation unit
+ double rz_deg = 0.0; // degrees
+};
+
+// Frame in which ModelTransform.a is expressed.
+// ModelLocal — pre-stage2 model coordinates, in the model's project length unit
+// ModelGlobal — post-stage2 model coordinates, in the model's map unit
+enum class AFrame { ModelLocal, ModelGlobal };
+
+// Stage 4 — the per-model placement within the federation. Authoring intent
+// is "rotate the model around `pivot`, then translate so that point `a` lands
+// at point `b`". Composed as
+//
+// R_local = R_z(rz) · R_y(ry) · R_x(rx) [intrinsic XYZ]
+// R_at_pivot = T(pivot_m) · R_local · T(-pivot_m)
+// stage4 = T(b_m - R_at_pivot · a_m) · R_at_pivot
+//
+// Numbers are stored in their original input unit (a in model project or map
+// unit per a_frame, b/pivot in federation unit) so that the user's typed
+// values round-trip without precision loss.
+struct ModelTransform {
+ AFrame a_frame = AFrame::ModelGlobal;
+ Eigen::Vector3d a = Eigen::Vector3d::Zero(); // model project / map unit
+ Eigen::Vector3d b = Eigen::Vector3d::Zero(); // federation unit
+ Eigen::Vector3d rxyz_deg = Eigen::Vector3d::Zero(); // degrees, intrinsic XYZ
+ Eigen::Vector3d pivot = Eigen::Vector3d::Zero(); // federation unit
+};
+
+// Per-model unit scales captured at load time. project_length_to_meters
+// comes from calculateUnitScale(file, "LENGTHUNIT"); map_unit_to_meters from
+// siScaleFromNamedUnit(getMapUnit(file)) and falls back to the project length
+// scale when the model has no MapUnit.
+struct ModelUnits {
+ double project_length_to_meters = 1.0;
+ double map_unit_to_meters = 1.0;
+};
+
+// 1 federation_unit -> N metres. Cached at the call site if needed.
+double federationUnitToMeters(const FederationConfig&);
+
+// Compose stage 3 (federation false origin) into a 4x4 matrix in metres.
+Eigen::Matrix4d composeFederationOrigin(const FederationOrigin&,
+ const FederationConfig&);
+
+// Compose stage 4 (per-model placement within the federation) into a 4x4
+// matrix in metres. `stage2_meters` is the model's georef matrix (e.g.
+// helmertMetersFromParameters · inv(wcs_meters)) — needed to lift `a` into
+// metres when a_frame == ModelLocal. Pass identity when stage 2 is disabled
+// or absent.
+Eigen::Matrix4d composeModelTransform(const ModelTransform&,
+ const FederationConfig& fed_cfg,
+ const ModelUnits& model_units,
+ const Eigen::Matrix4d& stage2_meters);
+
+#endif // FEDERATION_H