Merge remote-tracking branch 'remotes/origin/dev' into dev_baris_aabb_auto_mergeable

CityDoctorParent/Extensions/CityDoctorHealer/src/test/java/de/hft/stuttgart/citydoctor2/healing/TestHealer.java

@@ -150,15 +150,14 @@ public class TestHealer {
 
 		Checker c = new Checker(config, model);
 		c.runChecks();
-
-		Geometry geom = model.getBuildings().toList().get(0).getGeometries().get(0);
+		Building b = model.getBuildings().toList().get(0);
+		Geometry geom = b.getGeometries().get(0);
 
 		Healer healer = new Healer(c);
-		healer.setNumberOfIterations(33);
-		healer.healCityObject(model.getBuildings().toList().get(0));
+		healer.healCityObject(b);
 		c.runChecks();
-
 		assertFalse(geom.containsAnyError());
+
 	}
 
 	@Test
@@ -193,7 +192,6 @@ public class TestHealer {
 		Geometry geom = model.getBuildings().toList().get(0).getGeometries().get(0);
 
 		Healer healer = new Healer(c);
-		healer.setNumberOfIterations(83);
 		healer.healCityObject(model.getBuildings().toList().get(0));
 		c.runChecks();
 
@@ -213,7 +211,6 @@ public class TestHealer {
 		Geometry geom = model.getBuildings().toList().get(0).getGeometries().get(0);
 
 		Healer healer = new Healer(c);
-		healer.setNumberOfIterations(165);
 		healer.healCityObject(model.getBuildings().toList().get(0));
 		c.runChecks();
 
@@ -264,7 +261,6 @@ public class TestHealer {
 		Geometry geom = model.getBuildings().toList().get(0).getGeometries().get(0);
 
 		Healer healer = new Healer(c);
-		healer.setNumberOfIterations(45);
 		healer.healCityObject(model.getBuildings().toList().get(0));
 		c.runChecks();
 
@@ -282,7 +278,6 @@ public class TestHealer {
 
 
 		Healer healer = new Healer(c);
-		healer.setNumberOfIterations(45);
 		healer.healModel(model);
 	}
 	
@@ -299,7 +294,7 @@ public class TestHealer {
 		
 		Geometry geom = model.getBuildings().toList().get(0).getGeometries().get(0);
 		Healer healer = new Healer(c);
-		healer.setNumberOfIterations(100);
+
 		healer.healCityObject(model.getBuildings().toList().get(0));
 		
 		c.runChecks();

CityDoctorParent/Extensions/CityDoctorHealer/src/test/java/de/hft/stuttgart/citydoctor2/healing/TestUtil.java

@@ -31,7 +31,7 @@ public class TestUtil {
 	}
 
 	public static CityDoctorModel loadCityModel(String path, ValidationConfiguration config) throws CityGmlParseException, IOException, InvalidGmlFileException {
-		return CityGmlParser.parseCityGmlFile(path, config.getParserConfiguration());
+		return CityGmlParser.nestedCityGmlFileParse(path, config.getParserConfiguration());
 	}
 	
 	public static Polygon getPolygonById(String gmlId, CityDoctorModel model) {

CityDoctorParent/Extensions/CityDoctorHealerGUI/pom.xml

@@ -7,7 +7,7 @@
 	<parent>
 		<groupId>de.hft.stuttgart</groupId>
 		<artifactId>CityDoctorParent</artifactId>
-		<version>3.18.1</version>
+		<version>3.18.3</version>
 		<relativePath>../../pom.xml</relativePath>
 	</parent>
 	<artifactId>CityDoctorHealerGUI</artifactId>

CityDoctorParent/Extensions/CityDoctorHealerGUI/src/main/java/de/hft/stuttgart/citydoctor2/healer/gui/HealerController.java

@@ -31,15 +31,16 @@ import de.hft.stuttgart.citydoctor2.datastructure.Opening;
 import de.hft.stuttgart.citydoctor2.datastructure.Polygon;
 import de.hft.stuttgart.citydoctor2.gui.HighlightController;
 import de.hft.stuttgart.citydoctor2.gui.ListErrorVisitor;
-import de.hft.stuttgart.citydoctor2.gui.TriangulatedGeometry;
+import de.hft.stuttgart.citydoctor2.gui.gl.IndexSetBuilder;
+import de.hft.stuttgart.citydoctor2.gui.gl.SceneBuilder;
+import de.hft.stuttgart.citydoctor2.gui.gl.SceneData;
 import de.hft.stuttgart.citydoctor2.healer.Healer;
 import de.hft.stuttgart.citydoctor2.optimization.MeshGenerator;
 import de.hft.stuttgart.citydoctor2.utils.Copy;
 import javafx.collections.ObservableList;
 import javafx.scene.control.TextInputDialog;
 import javafx.scene.control.TreeItem;
-import javafx.scene.shape.CullFace;
-import javafx.scene.shape.DrawMode;
+import javafx.scene.paint.Color;
 
 public class HealerController {
 
@@ -53,11 +54,11 @@ public class HealerController {
 	private Geometry nextGeometry;
 
 	private Checker checker;
-	private CullFace culling = CullFace.BACK;
-	private DrawMode drawMode = DrawMode.FILL;
+	private boolean culling = false;
+	private boolean wireframe = false;
 
-	private TriangulatedGeometry nextTriangulatedGeometry;
-	private TriangulatedGeometry currentTriangulatedGeometry;
+	private SceneData currentScene;
+	private SceneData nextScene;
 
 	private ListErrorVisitor currentErrorVisitor;
 	private ListErrorVisitor nextErrorVisitor;
@@ -69,14 +70,54 @@ public class HealerController {
 
 	public HealerController(HealerView healerView) {
 		this.healerView = healerView;
-		this.currentHighlights = new HighlightController(healerView.getCurrentWorld());
-		this.nextHighlights = new HighlightController(healerView.getNextWorld());
+		this.currentHighlights = new HighlightController(healerView.getCurrentViewport());
+		this.nextHighlights = new HighlightController(healerView.getNextViewport());
+		currentHighlights.setCenterSupplier(() -> currentScene == null ? new double[3] : currentScene.center());
+		nextHighlights.setCenterSupplier(() -> nextScene == null ? new double[3] : nextScene.center());
 		currentErrorVisitor = new ListErrorVisitor(currentHighlights);
 		nextErrorVisitor = new ListErrorVisitor(nextHighlights);
-		healerView.translateZProperty().addListener((obs, oldV, newV) -> {
-			currentHighlights.changeScaling(-newV.doubleValue());
-			nextHighlights.changeScaling(-newV.doubleValue());
-		});
+	}
+
+	/** Installs the current scene into the current viewport and applies the current view options. */
+	private void showCurrentScene() {
+		currentHighlights.clearHighlights();
+		healerView.getCurrentViewport().setScene(currentScene);
+		// the viewport draws nothing until it is told which triangles are visible; the healer has no
+		// LOD/roof filtering, so show every triangle of the scene
+		healerView.getCurrentViewport().setIndexSet(allTriangles(currentScene));
+		healerView.getCurrentViewport().setWireframe(wireframe);
+		healerView.getCurrentViewport().setCulling(culling);
+	}
+
+	/** Installs the next scene into the next viewport and applies the current view options. */
+	private void showNextScene() {
+		nextHighlights.clearHighlights();
+		healerView.getNextViewport().setScene(nextScene);
+		// the viewport draws nothing until it is told which triangles are visible; the healer has no
+		// LOD/roof filtering, so show every triangle of the scene
+		healerView.getNextViewport().setIndexSet(allTriangles(nextScene));
+		healerView.getNextViewport().setWireframe(wireframe);
+		healerView.getNextViewport().setCulling(culling);
+	}
+
+	/** Builds an index set covering every triangle of the scene (no filtering). */
+	private static int[] allTriangles(SceneData scene) {
+		if (scene == null) {
+			return new int[0];
+		}
+		return IndexSetBuilder.build(scene.triangleMetas(), m -> true);
+	}
+
+	private void clearCurrentScene() {
+		currentScene = null;
+		currentHighlights.clearHighlights();
+		healerView.getCurrentViewport().clearScene();
+	}
+
+	private void clearNextScene() {
+		nextScene = null;
+		nextHighlights.clearHighlights();
+		healerView.getNextViewport().clearScene();
 	}
 	
 	public void showSimplyfication() {
@@ -91,8 +132,8 @@ public class HealerController {
 
 	public void setCurrentModel(CityDoctorModel model) {
 		if (this.model != model) {
-			healerView.getCurrentMeshGroup().getChildren().clear();
-			healerView.getNextMeshGroup().getChildren().clear();
+			clearCurrentScene();
+			clearNextScene();
 			healerView.getCurrentErrorList().getItems().clear();
 		}
 		this.model = model;
@@ -274,18 +315,14 @@ public class HealerController {
 		SelectableGeometry selectedGeometry = (SelectableGeometry) selectedItem;
 		currentGeometry = selectedGeometry.getGeometry();
 		currentFeature = selectedGeometry.getFeature();
-		currentTriangulatedGeometry = TriangulatedGeometry.of(currentGeometry);
-		currentErrorVisitor.setGeometry(currentTriangulatedGeometry);
-		currentTriangulatedGeometry.setCullFace(culling);
-		currentTriangulatedGeometry.setDrawMode(drawMode);
+		currentScene = SceneBuilder.fromPolygons(currentGeometry.getPolygons(), Color.WHITE);
 		healerView.setSelectedFeatureText(currentFeature.getGmlId().getGmlString());
 		healerView.setFeatureTypeText(currentFeature.getFeatureType().toString());
 		healerView.setGeometryText(currentGeometry.getLod().toString() + ", " + currentGeometry.getType().toString());
 		updateCurrentErrors();
 		healerView.zoomOutForBoundingBox(currentGeometry.calculateBoundingBox());
-		healerView.getCurrentMeshGroup().getChildren().clear();
-		healerView.getNextMeshGroup().getChildren().clear();
-		healerView.getCurrentMeshGroup().getChildren().addAll(currentTriangulatedGeometry.getMeshes());
+		showCurrentScene();
+		clearNextScene();
 		healerView.getNextStepBtn().setDisable(false);
 		healerView.getHealCompleteBtn().setDisable(false);
 		healerView.getAcceptBtn().setDisable(true);
@@ -322,12 +359,8 @@ public class HealerController {
 	}
 
 	private void updateNextGeometryView() {
-		nextTriangulatedGeometry = TriangulatedGeometry.of(nextGeometry);
-		nextErrorVisitor.setGeometry(nextTriangulatedGeometry);
-		nextTriangulatedGeometry.setCullFace(culling);
-		nextTriangulatedGeometry.setDrawMode(drawMode);
-		healerView.getNextMeshGroup().getChildren().clear();
-		healerView.getNextMeshGroup().getChildren().addAll(nextTriangulatedGeometry.getMeshes());
+		nextScene = SceneBuilder.fromPolygons(nextGeometry.getPolygons(), Color.WHITE);
+		showNextScene();
 		healerView.getAcceptBtn().setDisable(false);
 		healerView.getCancelBtn().setDisable(false);
 		healerView.getSolidInjectorBtn().setDisable(true);
@@ -346,12 +379,8 @@ public class HealerController {
 		Healer healer = new Healer(checker);
 		healer.heal(nextGeometry, nextFeature);
 		updateNextErrors();
-		nextTriangulatedGeometry = TriangulatedGeometry.of(nextGeometry);
-		nextErrorVisitor.setGeometry(nextTriangulatedGeometry);
-		nextTriangulatedGeometry.setCullFace(culling);
-		nextTriangulatedGeometry.setDrawMode(drawMode);
-		healerView.getNextMeshGroup().getChildren().clear();
-		healerView.getNextMeshGroup().getChildren().addAll(nextTriangulatedGeometry.getMeshes());
+		nextScene = SceneBuilder.fromPolygons(nextGeometry.getPolygons(), Color.WHITE);
+		showNextScene();
 		healerView.getAcceptBtn().setDisable(false);
 		healerView.getNextStepBtn().setDisable(true);
 		healerView.getHealCompleteBtn().setDisable(true);
@@ -414,14 +443,9 @@ public class HealerController {
 		currentGeometry = nextGeometry;
 		updateCurrentErrors();
 		healerView.getNextErrorList().getItems().clear();
-		healerView.getCurrentMeshGroup().getChildren().clear();
-		healerView.getCurrentMeshGroup().getChildren().addAll(nextTriangulatedGeometry.getMeshes());
-		currentTriangulatedGeometry = nextTriangulatedGeometry;
-		currentErrorVisitor.setGeometry(currentTriangulatedGeometry);
-		nextTriangulatedGeometry = null;
-//		nextHighlights = new HighlightController(healerView.getNextWorld());
-//		nextErrorVisitor = new ListErrorVisitor(nextHighlights);
-		healerView.getNextMeshGroup().getChildren().clear();
+		currentScene = nextScene;
+		showCurrentScene();
+		clearNextScene();
 		healerView.getHealCompleteBtn().setDisable(false);
 		healerView.getNextStepBtn().setDisable(false);
 		healerView.getAcceptBtn().setDisable(true);
@@ -429,27 +453,15 @@ public class HealerController {
 	}
 
 	public void setWireframe(boolean b) {
-		if (b) {
-			drawMode = DrawMode.LINE;
-		} else {
-			drawMode = DrawMode.FILL;
-		}
-		if (currentTriangulatedGeometry != null) {
-			currentTriangulatedGeometry.setDrawMode(drawMode);
-		}
-		if (nextTriangulatedGeometry != null) {
-			nextTriangulatedGeometry.setDrawMode(drawMode);
-		}
+		this.wireframe = b;
+		healerView.getCurrentViewport().setWireframe(b);
+		healerView.getNextViewport().setWireframe(b);
 	}
 
-	public void setCulling(CullFace culling) {
+	public void setCulling(boolean culling) {
 		this.culling = culling;
-		if (currentTriangulatedGeometry != null) {
-			currentTriangulatedGeometry.setCullFace(culling);
-		}
-		if (nextTriangulatedGeometry != null) {
-			nextTriangulatedGeometry.setCullFace(culling);
-		}
+		healerView.getCurrentViewport().setCulling(culling);
+		healerView.getNextViewport().setCulling(culling);
 	}
 
 	public void cancelClicked() {
@@ -457,14 +469,13 @@ public class HealerController {
 			return;
 		}
 		healerView.getNextErrorList().getItems().clear();
-		healerView.getNextMeshGroup().getChildren().clear();
+		clearNextScene();
 		healerView.getAcceptBtn().setDisable(true);
 		healerView.getCancelBtn().setDisable(true);
 		healerView.getNextStepBtn().setDisable(false);
 		healerView.getHealCompleteBtn().setDisable(false);
 		nextFeature = null;
 		nextGeometry = null;
-		nextTriangulatedGeometry = null;
 	}
 
 	public void currentHighlight(CheckError err) {
@@ -527,8 +538,8 @@ public class HealerController {
 		healerView.getHealCompleteBtn().setDisable(true);
 		healerView.getCurrentErrorList().getItems().clear();
 		healerView.getNextErrorList().getItems().clear();
-		healerView.getCurrentMeshGroup().getChildren().clear();
-		healerView.getNextMeshGroup().getChildren().clear();
+		clearCurrentScene();
+		clearNextScene();
 		healerView.setSelectedFeatureText("");
 		healerView.setFeatureTypeText("");
 		healerView.setGeometryText("");

CityDoctorParent/Extensions/CityDoctorHealerGUI/src/main/java/de/hft/stuttgart/citydoctor2/healer/gui/HealerToolbar.java

@@ -13,7 +13,6 @@ import javafx.scene.image.Image;
 import javafx.scene.image.ImageView;
 import javafx.scene.layout.HBox;
 import javafx.scene.layout.Priority;
-import javafx.scene.shape.CullFace;
 
 public class HealerToolbar {
 
@@ -63,13 +62,7 @@ public class HealerToolbar {
 		wireframeImage.setImage(new Image(MainToolBar.class.getResourceAsStream("icons/wireframe32x32.png")));
 		simplyImageView.setImage(new Image(HealerToolbar.class.getResourceAsStream("autopro32x32.png")));
 		wireframeBtn.selectedProperty().addListener((obs, oldV, newV) -> controller.setWireframe(newV));
-		cullingBtn.selectedProperty().addListener((obs, oldV, newV) -> {
-			if (Boolean.TRUE.equals(newV)) {
-				controller.setCulling(CullFace.BACK);
-			} else {
-				controller.setCulling(CullFace.NONE);
-			}
-		});
+		cullingBtn.selectedProperty().addListener((obs, oldV, newV) -> controller.setCulling(Boolean.TRUE.equals(newV)));
 		saveBtn.setOnAction(ae -> cdController.askAndSave());
 		saveBtn.setDisable(true);
 		saveImage.setImage(new Image(MainWindow.class.getResourceAsStream("icons/save.png")));

CityDoctorParent/Extensions/CityDoctorHealerGUI/src/main/java/de/hft/stuttgart/citydoctor2/healer/gui/HealerView.java

@@ -13,16 +13,10 @@ import de.hft.stuttgart.citydoctor2.datastructure.CityDoctorModel;
 import de.hft.stuttgart.citydoctor2.gui.FilterPane;
 import de.hft.stuttgart.citydoctor2.gui.MainWindow;
 import de.hft.stuttgart.citydoctor2.gui.View;
-import javafx.beans.property.DoubleProperty;
-import javafx.beans.property.SimpleDoubleProperty;
+import de.hft.stuttgart.citydoctor2.gui.gl.GLViewport;
 import javafx.fxml.FXML;
 import javafx.fxml.FXMLLoader;
-import javafx.scene.AmbientLight;
-import javafx.scene.Group;
 import javafx.scene.Node;
-import javafx.scene.PerspectiveCamera;
-import javafx.scene.SceneAntialiasing;
-import javafx.scene.SubScene;
 import javafx.scene.control.Button;
 import javafx.scene.control.Label;
 import javafx.scene.control.ListView;
@@ -30,11 +24,9 @@ import javafx.scene.control.Tooltip;
 import javafx.scene.control.cell.TextFieldListCell;
 import javafx.scene.image.Image;
 import javafx.scene.image.ImageView;
-import javafx.scene.input.MouseButton;
 import javafx.scene.layout.HBox;
 import javafx.scene.layout.Pane;
-import javafx.scene.paint.Color;
-import javafx.scene.transform.Rotate;
+import javafx.scene.layout.Region;
 import javafx.stage.Window;
 import javafx.util.StringConverter;
 
@@ -42,10 +34,6 @@ public class HealerView extends View {
 
 	private static final Logger logger = LogManager.getLogger(HealerView.class);
 
-	private static final double CAMERA_TRANSLATE_Z = -100.0;
-	private static final double CAMERA_INITIAL_X_ANGLE = 20.0;
-	private static final double CAMERA_INITIAL_Y_ANGLE = 120.0;
-
 	private Image image;
 
 	private Node healerWindow;
@@ -55,13 +43,6 @@ public class HealerView extends View {
 	private ChooseFeatureDialog chooseFeatureDialog;
 	private HealerToolbar toolBar;
 
-	private DoubleProperty translateZ;
-	private DoubleProperty cameraXRot;
-	private DoubleProperty cameraYRot;
-
-	private double dragX;
-	private double dragY;
-
 	@FXML
 	private Button fixBtn;
 
@@ -121,11 +102,9 @@ public class HealerView extends View {
 	
 	@FXML
 	private Button meshBtn;
-	
-	private Group currentWorld;
-	private Group nextWorld;
-	private Group currentMeshGroup;
-	private Group nextMeshGroup;
+
+	private GLViewport currentViewport;
+	private GLViewport nextViewport;
 
 	public HealerView() {
 		image = new Image(getClass().getResourceAsStream("healing.png"));
@@ -198,104 +177,40 @@ public class HealerView extends View {
 	}
 
 	private void setup3dViews() {
-		translateZ = new SimpleDoubleProperty(CAMERA_TRANSLATE_Z);
-		cameraXRot = new SimpleDoubleProperty(CAMERA_INITIAL_X_ANGLE);
-		cameraYRot = new SimpleDoubleProperty(CAMERA_INITIAL_Y_ANGLE);
-
-		buildCurrent3dView();
-		buildNext3dView();
-	}
-
-	private void buildCurrent3dView() {
-		Group currentRoot = new Group();
-		SubScene currentScene = new SubScene(currentRoot, 500, 300, true, SceneAntialiasing.BALANCED);
-		currentScene.heightProperty().bind(currentCanvas.heightProperty());
-		currentScene.widthProperty().bind(currentCanvas.widthProperty());
-		currentScene.setFill(Color.AZURE);
-		currentCanvas.getChildren().add(currentScene);
-		currentWorld = new Group();
-		currentRoot.getChildren().add(currentWorld);
-		currentMeshGroup = new Group();
-		currentWorld.getChildren().add(currentMeshGroup);
-
-		AmbientLight al = new AmbientLight(Color.WHITE);
-		currentRoot.getChildren().add(al);
-
-		PerspectiveCamera currentCamera = new PerspectiveCamera(true);
-		currentCamera.setNearClip(0.1);
-		currentCamera.setFarClip(10000d);
-		currentCamera.translateZProperty().bind(translateZ);
-		Rotate cameraZRotation = new Rotate();
-		Rotate cameraXRotation = new Rotate();
-		cameraXRotation.setAxis(Rotate.X_AXIS);
-		cameraZRotation.setAxis(Rotate.Z_AXIS);
-		cameraZRotation.angleProperty().bind(cameraXRot);
-		cameraXRotation.angleProperty().bind(cameraYRot);
-		currentWorld.getTransforms().add(cameraXRotation);
-		currentWorld.getTransforms().add(cameraZRotation);
-		currentRoot.getChildren().add(currentCamera);
-		currentScene.setCamera(currentCamera);
-		setupMeshViewControls(currentCanvas);
-	}
-
-	private void buildNext3dView() {
-		Group nextRoot = new Group();
-		SubScene nextScene = new SubScene(nextRoot, 500, 300, true, SceneAntialiasing.BALANCED);
-		nextScene.heightProperty().bind(nextCanvas.heightProperty());
-		nextScene.widthProperty().bind(nextCanvas.widthProperty());
-		nextScene.setFill(Color.AZURE);
-		nextCanvas.getChildren().add(nextScene);
-		nextWorld = new Group();
-		nextRoot.getChildren().add(nextWorld);
-		nextMeshGroup = new Group();
-		nextWorld.getChildren().add(nextMeshGroup);
-
-		AmbientLight al = new AmbientLight(Color.WHITE);
-		nextRoot.getChildren().add(al);
-
-		PerspectiveCamera nextCamera = new PerspectiveCamera(true);
-		nextCamera.setNearClip(0.1);
-		nextCamera.setFarClip(10000d);
-		nextCamera.translateZProperty().bind(translateZ);
-		Rotate cameraZRotation = new Rotate();
-		Rotate cameraXRotation = new Rotate();
-		cameraXRotation.setAxis(Rotate.X_AXIS);
-		cameraZRotation.setAxis(Rotate.Z_AXIS);
-		cameraZRotation.angleProperty().bind(cameraXRot);
-		cameraXRotation.angleProperty().bind(cameraYRot);
-		nextWorld.getTransforms().add(cameraXRotation);
-		nextWorld.getTransforms().add(cameraZRotation);
-		nextRoot.getChildren().add(nextCamera);
-		nextScene.setCamera(nextCamera);
-		setupMeshViewControls(nextCanvas);
+		currentViewport = new GLViewport();
+		nextViewport = new GLViewport();
+		attachViewport(currentCanvas, currentViewport);
+		attachViewport(nextCanvas, nextViewport);
+		coupleViewports();
+	}
+
+	private void attachViewport(Pane canvas, GLViewport viewport) {
+		Region node = viewport.getNode();
+		node.prefWidthProperty().bind(canvas.widthProperty());
+		node.prefHeightProperty().bind(canvas.heightProperty());
+		canvas.getChildren().add(node);
+	}
+
+	/**
+	 * Keeps the two viewports' cameras in sync: orbiting/panning/zooming one mirrors the camera into
+	 * the other and redraws it, reproducing the legacy shared-camera behaviour of the dual SubScenes.
+	 */
+	private void coupleViewports() {
+		currentViewport.setInteractionListener(() -> {
+			nextViewport.camera().copyOrbitFrom(currentViewport.camera());
+			nextViewport.requestRedraw();
+		});
+		nextViewport.setInteractionListener(() -> {
+			currentViewport.camera().copyOrbitFrom(nextViewport.camera());
+			currentViewport.requestRedraw();
+		});
 	}
 
 	public void zoomOutForBoundingBox(BoundingBox b) {
-		double longestSide = b.getDiagonalLength() * 0.4;
-		double d = longestSide / Math.tan(Math.toRadians(30) / 2);
-		translateZ.set(-d);
-	}
-
-	private void setupMeshViewControls(Pane canvas) {
-		canvas.setOnMousePressed(me -> {
-			if (me.getButton() == MouseButton.PRIMARY) {
-				dragX = me.getScreenX();
-				dragY = me.getScreenY();
-			}
-		});
-
-		canvas.setOnScroll(se -> translateZ.set(translateZ.get() + se.getDeltaY() / 10d));
-
-		canvas.setOnMouseDragged(me -> {
-			if (me.getButton() == MouseButton.PRIMARY) {
-				double deltaX = me.getScreenX() - dragX;
-				double deltaY = me.getScreenY() - dragY;
-				dragX = me.getScreenX();
-				dragY = me.getScreenY();
-				cameraXRot.set(cameraXRot.get() + ((deltaX / 3d) % 360));
-				cameraYRot.set(cameraYRot.get() + ((deltaY / 3d) % 360));
-			}
-		});
+		currentViewport.camera().zoomOutForBoundingBox(b.getDiagonalLength());
+		nextViewport.camera().copyOrbitFrom(currentViewport.camera());
+		currentViewport.requestRedraw();
+		nextViewport.requestRedraw();
 	}
 
 	@Override
@@ -330,12 +245,12 @@ public class HealerView extends View {
 		return chooseFeatureDialog;
 	}
 
-	public Group getCurrentWorld() {
-		return currentWorld;
+	public GLViewport getCurrentViewport() {
+		return currentViewport;
 	}
 
-	public Group getNextWorld() {
-		return nextWorld;
+	public GLViewport getNextViewport() {
+		return nextViewport;
 	}
 
 	public void setSelectedFeatureText(String text) {
@@ -378,18 +293,6 @@ public class HealerView extends View {
 		return cancelButton;
 	}
 
-	public DoubleProperty translateZProperty() {
-		return translateZ;
-	}
-
-	public Group getNextMeshGroup() {
-		return nextMeshGroup;
-	}
-
-	public Group getCurrentMeshGroup() {
-		return currentMeshGroup;
-	}
-
 	public Button getSolidInjectorBtn() {
 		return solidInjectorBtn;
 	}

CityDoctorParent/Extensions/CityDoctorHealerGUI/src/main/resources/log4j2.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE Configuration>
+<Configuration status="INFO">
+    <Appenders>
+        <Console name="console" target="SYSTEM_OUT">
+            <PatternLayout
+                    pattern="[%-5level] %d{HH:mm:ss.SSS} %c{1} - %msg%n" />
+        </Console>
+    </Appenders>
+    <Loggers>
+        <Root level="debug" additivity="false">
+            <AppenderRef ref="console" />
+        </Root>
+        <Logger name="com.zaxxer.hikari" level="INFO" additivity="false">
+            <AppenderRef ref="console"/>
+        </Logger>
+    </Loggers>
+</Configuration>
\ No newline at end of file

CityDoctorParent/Extensions/CityDoctorHealerGenetic/pom.xml

@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>de.hft.stuttgart</groupId>
 		<artifactId>CityDoctorParent</artifactId>
-		<version>3.18.1</version>
+		<version>3.18.2</version>
 		<relativePath>../../pom.xml</relativePath>
 	</parent>
 	<artifactId>CityDoctorHealerGenetic</artifactId>

CityDoctorParent/pom.xml

@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>de.hft.stuttgart</groupId>
     <artifactId>CityDoctorParent</artifactId>
-    <version>3.18.1</version>
+    <version>3.18.3</version>
     <packaging>pom</packaging>
     <name>CityDoctorParent</name>
     <properties>
@@ -28,6 +28,11 @@
             <id>sonartype</id>
             <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
         </repository>
+        <!-- JogAmp publishes JOGL/GlueGen 2.4.0+ here; Maven Central only has up to 2.3.2. -->
+        <repository>
+            <id>jogamp</id>
+            <url>https://jogamp.org/deployment/maven/</url>
+        </repository>
     </repositories>
     <build>
         <pluginManagement>
@@ -41,6 +46,9 @@
                         <excludes>
                             <exclude>**/SolidSelfIntCheckFalsePositiveBigMeshTest.java</exclude>
                         </excludes>
+                        <excludedGroups>
+                            de.hft.stuttgart.citydoctor2.connect.edge.CppTest
+                        </excludedGroups>
                     </configuration>
                 </plugin>
             </plugins>
@@ -165,7 +173,7 @@
             <dependency>
                 <groupId>org.jogamp.gluegen</groupId>
                 <artifactId>gluegen-rt-main</artifactId>
-                <version>2.3.2</version>
+                <version>2.5.0</version>
             </dependency>
             <dependency>
                 <groupId>gov.nist.math</groupId>
@@ -175,7 +183,7 @@
             <dependency>
                 <groupId>org.jogamp.jogl</groupId>
                 <artifactId>jogl-all-main</artifactId>
-                <version>2.3.2</version>
+                <version>2.5.0</version>
             </dependency>
             <dependency>
                 <groupId>org.apache.logging.log4j</groupId>
@@ -303,9 +311,9 @@
         <!--CityDoctor2 Extension Modules-->
         <module>Extensions/CityDoctorGUI</module>
 <!--        <module>Extensions/CityDoctorAutoPro</module>-->
-<!--        <module>Extensions/CityDoctorHealer</module>-->
+        <module>Extensions/CityDoctorHealer</module>
 <!--        <module>Extensions/CityDoctorHealerGenetic</module>-->
-<!--        <module>Extensions/CityDoctorHealerGUI</module>-->
+        <module>Extensions/CityDoctorHealerGUI</module>
 
     </modules>
 </project>
\ No newline at end of file

DBSettings.properties

+! Embedded database configuration
+! Remove # at the beginning of a parameter line to override the value.
+
+! Directory for the database file. DEFAULT: \\database\\
+# database.directory=\\database\\
+! Name of the database file. DEFAULT: cd_db
+# database.name=cd_db
+
+! Sets a limit for the number of pooled connections to the embedded database. DEFAULT: 10
+! If not overridden CityDoctor will use the number of available CPU cores as limit.
+# database.connectionPoolSize=10
+
+! If temp mode is enabled the database-file will be created in the System's TEMP directory. DEFAULT: false
+# database.tempMode=false
+
+! If in-memory mode is enabled the database will be created in the Systems RAM. DEFAULT: false
+! WARNING: Enabling in-memory mode can lead to out-of-memory errors when loading bigger CityGML files.
+# database.inMemoryMode=false
+
+! If fallback is enabled CityDoctor will attempt to use the in-memory mode if database-file creation fails DEFAULT: true
+# database.attemptFallback=true
+
+! If debug mode is enabled the embedded database will start in automatic mixed mode DEFAULT: false
+! NOTE: Activating this mode will start a local server with random ports. This may trigger a Firewall request, which can be safely denied.
+! NOTE: This server is only accessible locally and automatically rejects any remote connections.
+# database.debugMode=false
+
+
+
+

README.md

@@ -43,7 +43,7 @@ Use [Maven](https://maven.apache.org/) to build CityDoctor2.
 
 ```bash
 cd CityDoctorParent
-mvn install
+mvn clean install -P create-binaries 
 ```
 
 CityDoctor2 uses the [quality ade plugin](https://transfer.hft-stuttgart.de/gitlab/betzms/qualityade). A jar is provided in a local repository for ease of use.
@@ -55,14 +55,16 @@ Once built there is a CityDoctorValidation-\<version\>.zip file in the target fo
 There is a start script included in the binary releases of citydoctor. An example start command looks like this:
 
 ```bash
-java -classpath libs/*;plugins/*;CityDoctorValidation-<version>.jar de.hft.stuttgart.citydoctor2.CityDoctorValidation -in <path-to-gml-file>.gml -config <path-to-validation-config>.yml -xmlReport <path-to-xml-output>.xml -pdfReport <path-to-pdf-output>.pdf -out <path-to-output-gml>.gml
+java -classpath libs/*;plugins/*;CityDoctorValidation-<version>.jar de.hft.stuttgart.citydoctor2.CityDoctorValidation -in <path-to-gml-file>.gml -config <path-to-validation-config>.yml -xmlReport <path-to-xml-output>.xml -pdfReport <path-to-pdf-output>.pdf -out <path-to-output-gml>.gml -db_location <path-for-database-file> -db_settings <path-to-database-settings-file>.properties
 ```
 
 Notes:
 
-- -xmlReport, -pdfReport and -out are optional
-- If a ZIP file is given as input, CityDoctor2 will check all contained CityGML files. The -out parameter is required in
-  this case
+- -xmlReport, -pdfReport, -out, -db_location and -db_settings are optional
+- Paths will be resolved from CityDoctor's working directory
+- See [DBSettings.properties](DBSettings.properties) for the formatting of the database-settings file
+- The -db_location parameter takes precedence over the location set in the database-settings file
+- The start scripts included in the binary releases have -db_location set to the system's temp directory
 
 ## Extension modules
 

docs/superpowers/plans/2026-06-18-opengl-3d-view.md

+# OpenGL 3D View Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the JavaFX `SubScene`/`MeshView` 3D view in `CityDoctorGUI` with an OpenGL-rendered viewport (openglfx-jogl, GL 3.3 core) that orbits/zooms/pans smoothly on whole-city models.
+
+**Architecture:** A single global static VBO holds all triangle vertices (`position`, baked-shade `color`, `polygonId`); one `glDrawElements` per frame draws an index set rebuilt on filter/LOD changes. GPU color-picking (off-screen FBO + readback) resolves clicks to polygons/vertices/edges. Selection is a shader `selectedId` tint; vertex/edge highlight markers live in a small dynamic overlay buffer. The pure math/data core is unit-tested (TDD); the GL/openglfx glue is verified by running the app.
+
+**Tech Stack:** Java 17, JavaFX, JUnit 4, JOGL (`com.jogamp.opengl.GL3`), openglfx 4.1.19 (`com.huskerdev.openglfx.canvas.GLCanvas`, `com.huskerdev.openglfx.jogl.JOGLExecutor`, `com.huskerdev.grapl.gl.GLProfile`), Maven.
+
+**Key conventions:**
+- New code lives in package `de.hft.stuttgart.citydoctor2.gui.gl` under
+  `CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/`.
+- Tests mirror under `.../src/test/java/de/hft/stuttgart/citydoctor2/gui/gl/`.
+- Shaders live under `CityDoctorParent/Extensions/CityDoctorGUI/src/main/resources/de/hft/stuttgart/citydoctor2/gui/gl/`.
+- All Maven commands run from `CityDoctorParent/`. First run uses `-am` to build dependency modules;
+  later runs may add `-o` (offline) if local `.m2` is populated.
+- Test a single class with:
+  `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=ClassName test`
+- JUnit 4 (`org.junit.Test`, `org.junit.Assert.*`) — matches the existing `junit` dependency.
+
+**openglfx API reference (verified against 4.1.19 in local `.m2`):**
+- `GLCanvas` extends `javafx.scene.layout.Region`. Construct: `new GLCanvas(new JOGLExecutor(), GLProfile.CORE)`.
+- `canvas.addOnRenderEvent(Consumer<GLRenderEvent>)`, `addOnReshapeEvent`, `addOnInitEvent`, `addOnDisposeEvent`.
+- In the render consumer, cast: `JOGLRenderEvent e = (JOGLRenderEvent) ev;` then `e.getGl()` → `GL3`,
+  `e.width`, `e.height`, `e.fbo` (public fields). **openglfx binds `e.fbo` as the draw target before
+  calling.** After using our own FBO (picking) we must rebind `e.fbo`.
+
+---
+
+## Phase 1 — Pure core (TDD)
+
+These tasks have no GL dependency and run fully headless.
+
+### Task 1: Primitive growable arrays (`FloatList`, `IntList`)
+
+Needed so the mesh builder can accumulate millions of floats/ints without boxing.
+
+**Files:**
+- Create: `.../gui/gl/FloatList.java`
+- Create: `.../gui/gl/IntList.java`
+- Test: `.../test/.../gui/gl/FloatListTest.java`
+
+- [ ] **Step 1: Write the failing test**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import org.junit.Test;
+
+public class FloatListTest {
+
+    @Test
+    public void growsBeyondInitialCapacityAndPreservesOrder() {
+        FloatList list = new FloatList(2);
+        for (int i = 0; i < 10; i++) {
+            list.add(i);
+        }
+        assertEquals(10, list.size());
+        float[] expected = {0,1,2,3,4,5,6,7,8,9};
+        assertArrayEquals(expected, list.toArray(), 0.0f);
+    }
+
+    @Test
+    public void addThreeAddsAllInOrder() {
+        FloatList list = new FloatList(1);
+        list.add(1f, 2f, 3f);
+        assertArrayEquals(new float[]{1,2,3}, list.toArray(), 0.0f);
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=FloatListTest test`
+Expected: compilation failure / FAIL (`FloatList` does not exist).
+
+- [ ] **Step 3: Implement `FloatList` and `IntList`**
+
+```java
+// FloatList.java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import java.util.Arrays;
+
+/** Growable primitive float array to avoid boxing when building large vertex buffers. */
+public class FloatList {
+    private float[] data;
+    private int size;
+
+    public FloatList() { this(1024); }
+    public FloatList(int initialCapacity) { data = new float[Math.max(1, initialCapacity)]; }
+
+    public void add(float v) {
+        ensure(size + 1);
+        data[size++] = v;
+    }
+
+    public void add(float a, float b, float c) {
+        ensure(size + 3);
+        data[size++] = a;
+        data[size++] = b;
+        data[size++] = c;
+    }
+
+    private void ensure(int capacity) {
+        if (capacity > data.length) {
+            int newCap = data.length;
+            while (newCap < capacity) {
+                newCap <<= 1;
+            }
+            data = Arrays.copyOf(data, newCap);
+        }
+    }
+
+    public int size() { return size; }
+
+    public float[] toArray() { return Arrays.copyOf(data, size); }
+}
+```
+
+```java
+// IntList.java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import java.util.Arrays;
+
+/** Growable primitive int array. */
+public class IntList {
+    private int[] data;
+    private int size;
+
+    public IntList() { this(1024); }
+    public IntList(int initialCapacity) { data = new int[Math.max(1, initialCapacity)]; }
+
+    public void add(int v) {
+        if (size + 1 > data.length) {
+            data = Arrays.copyOf(data, data.length << 1);
+        }
+        data[size++] = v;
+    }
+
+    public int get(int index) { return data[index]; }
+
+    public int size() { return size; }
+
+    public int[] toArray() { return Arrays.copyOf(data, size); }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=FloatListTest test`
+Expected: PASS (BUILD SUCCESS, Tests run: 2, Failures: 0).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/FloatList.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/IntList.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/test/java/de/hft/stuttgart/citydoctor2/gui/gl/FloatListTest.java
+git commit -m "Add primitive growable FloatList/IntList for GL buffer building"
+```
+
+---
+
+### Task 2: `PickingCodec` (id ↔ RGB)
+
+**Files:**
+- Create: `.../gui/gl/PickingCodec.java`
+- Test: `.../test/.../gui/gl/PickingCodecTest.java`
+
+- [ ] **Step 1: Write the failing test**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import static org.junit.Assert.assertEquals;
+import org.junit.Test;
+
+public class PickingCodecTest {
+
+    @Test
+    public void roundTripsIdsThroughRgbBytes() {
+        int[] ids = {1, 255, 256, 65535, 65536, 16777215};
+        for (int id : ids) {
+            int r = PickingCodec.red(id);
+            int g = PickingCodec.green(id);
+            int b = PickingCodec.blue(id);
+            assertEquals(id, PickingCodec.decode(r, g, b));
+        }
+    }
+
+    @Test
+    public void blackDecodesToZeroBackground() {
+        assertEquals(0, PickingCodec.decode(0, 0, 0));
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=PickingCodecTest test`
+Expected: FAIL (`PickingCodec` does not exist).
+
+- [ ] **Step 3: Implement**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+/** Encodes integer ids into RGB bytes for GPU color-picking. Id 0 is reserved for background. */
+public final class PickingCodec {
+
+    private PickingCodec() {}
+
+    public static int red(int id)   { return id & 0xFF; }
+    public static int green(int id) { return (id >> 8) & 0xFF; }
+    public static int blue(int id)  { return (id >> 16) & 0xFF; }
+
+    public static int decode(int r, int g, int b) {
+        return (r & 0xFF) | ((g & 0xFF) << 8) | ((b & 0xFF) << 16);
+    }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=PickingCodecTest test`
+Expected: PASS (Tests run: 2).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/PickingCodec.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/test/java/de/hft/stuttgart/citydoctor2/gui/gl/PickingCodecTest.java
+git commit -m "Add PickingCodec for color-picking id encoding"
+```
+
+---
+
+### Task 3: `PickRegistry` (id → clicked target)
+
+Allocates ids and resolves a picked id back to the model object (`Polygon`, `Vertex`, or `Edge`). Id `n`
+maps to list index `n-1`; id `0` is background (null).
+
+**Files:**
+- Create: `.../gui/gl/PickRegistry.java`
+- Test: `.../test/.../gui/gl/PickRegistryTest.java`
+
+- [ ] **Step 1: Write the failing test**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+import org.junit.Test;
+
+public class PickRegistryTest {
+
+    @Test
+    public void assignsSequentialNonZeroIdsAndResolvesThem() {
+        PickRegistry reg = new PickRegistry();
+        Object a = "a";
+        Object b = "b";
+        int idA = reg.register(a);
+        int idB = reg.register(b);
+        assertEquals(1, idA);
+        assertEquals(2, idB);
+        assertEquals(a, reg.resolve(idA));
+        assertEquals(b, reg.resolve(idB));
+    }
+
+    @Test
+    public void resolvesBackgroundAndOutOfRangeToNull() {
+        PickRegistry reg = new PickRegistry();
+        reg.register("a");
+        assertNull(reg.resolve(0));
+        assertNull(reg.resolve(99));
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=PickRegistryTest test`
+Expected: FAIL (`PickRegistry` does not exist).
+
+- [ ] **Step 3: Implement**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/** Maps picking ids (1-based) to the model objects they represent. */
+public class PickRegistry {
+
+    private final List<Object> targets = new ArrayList<>();
+
+    /** Registers a target and returns its non-zero picking id. */
+    public int register(Object target) {
+        targets.add(target);
+        return targets.size(); // id = index + 1
+    }
+
+    /** Resolves a picking id to its target, or null for background / unknown id. */
+    public Object resolve(int id) {
+        if (id <= 0 || id > targets.size()) {
+            return null;
+        }
+        return targets.get(id - 1);
+    }
+
+    public int size() { return targets.size(); }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=PickRegistryTest test`
+Expected: PASS (Tests run: 2).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/PickRegistry.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/test/java/de/hft/stuttgart/citydoctor2/gui/gl/PickRegistryTest.java
+git commit -m "Add PickRegistry mapping picking ids to model objects"
+```
+
+---
+
+### Task 4: `ShadeColor` (extract existing fake shading)
+
+Extracts the per-polygon shade math from `TriangulatedGeometry.calculateMaterial` into a pure function so
+it can be baked into vertex colors and unit-tested. `javafx.scene.paint.Color` instantiates without the FX
+toolkit, so this is headless-safe.
+
+**Files:**
+- Create: `.../gui/gl/ShadeColor.java`
+- Test: `.../test/.../gui/gl/ShadeColorTest.java`
+
+- [ ] **Step 1: Write the failing test**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+import de.hft.stuttgart.citydoctor2.math.Vector3d;
+import javafx.scene.paint.Color;
+import org.junit.Test;
+
+public class ShadeColorTest {
+
+    @Test
+    public void brightnessStaysWithinExpectedBand() {
+        // Shade brightness is acos(normal.AXIS)/PI * 0.6 + 0.3 -> always within [0.3, 0.9].
+        Vector3d[] normals = {
+            new Vector3d(1, 0, 0), new Vector3d(0, 1, 0), new Vector3d(0, 0, 1),
+            new Vector3d(-1, 0, 0), new Vector3d(0.3, -0.7, 0.5)
+        };
+        for (Vector3d n : normals) {
+            Color c = ShadeColor.shade(n.normalize(), Color.WHITE);
+            assertTrue("brightness >= 0.3", c.getBrightness() >= 0.3 - 1e-6);
+            assertTrue("brightness <= 0.9", c.getBrightness() <= 0.9 + 1e-6);
+        }
+    }
+
+    @Test
+    public void matchesLegacyFormulaForKnownNormal() {
+        Vector3d axis = new Vector3d(19, 0.8, 1.5).normalize();
+        Vector3d normal = new Vector3d(0, 0, 1).normalize();
+        double cos = Math.max(-1.0, Math.min(1.0, normal.dot(axis)));
+        double shade = Math.acos(cos) / Math.PI * 0.6 + 0.3;
+        Color expected = Color.WHITE.deriveColor(0, 1.0, shade, 1.0);
+        Color actual = ShadeColor.shade(normal, Color.WHITE);
+        assertEquals(expected.getRed(),   actual.getRed(),   1e-9);
+        assertEquals(expected.getGreen(), actual.getGreen(), 1e-9);
+        assertEquals(expected.getBlue(),  actual.getBlue(),  1e-9);
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=ShadeColorTest test`
+Expected: FAIL (`ShadeColor` does not exist).
+
+- [ ] **Step 3: Implement**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import de.hft.stuttgart.citydoctor2.math.UnitVector3d;
+import de.hft.stuttgart.citydoctor2.math.Vector3d;
+import javafx.scene.paint.Color;
+
+/**
+ * Computes the surface-differentiation shade used by the legacy renderer: brightness derived from the
+ * angle between the polygon normal and a fixed axis. Not physical lighting; only makes adjacent faces
+ * distinguishable. Ported from {@code TriangulatedGeometry.calculateMaterial}.
+ */
+public final class ShadeColor {
+
+    private static final UnitVector3d AXIS = new Vector3d(19, 0.8, 1.5).normalize();
+
+    private ShadeColor() {}
+
+    public static Color shade(Vector3d normal, Color base) {
+        double cos = normal.dot(AXIS);
+        // clamp to acos domain; raw dot can drift slightly outside [-1,1] for near-parallel normals
+        cos = Math.max(-1.0, Math.min(1.0, cos));
+        double brightness = Math.acos(cos) / Math.PI * 0.6 + 0.3; // -> [0.3, 0.9]
+        return base.deriveColor(0, 1.0, brightness, 1.0);
+    }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=ShadeColorTest test`
+Expected: PASS (Tests run: 2).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/ShadeColor.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/test/java/de/hft/stuttgart/citydoctor2/gui/gl/ShadeColorTest.java
+git commit -m "Extract fake-shading math into pure ShadeColor"
+```
+
+---
+
+### Task 5: `Mat4` (column-major 4x4 matrix math)
+
+**Files:**
+- Create: `.../gui/gl/Mat4.java`
+- Test: `.../test/.../gui/gl/Mat4Test.java`
+
+- [ ] **Step 1: Write the failing test**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import org.junit.Test;
+
+public class Mat4Test {
+
+    @Test
+    public void identityTimesVectorIsUnchanged() {
+        float[] v = Mat4.transform(Mat4.identity(), 2, 3, 4, 1);
+        assertArrayEquals(new float[]{2, 3, 4, 1}, v, 1e-6f);
+    }
+
+    @Test
+    public void translationMovesPoint() {
+        float[] m = Mat4.translation(5, -2, 1);
+        float[] v = Mat4.transform(m, 1, 1, 1, 1);
+        assertArrayEquals(new float[]{6, -1, 2, 1}, v, 1e-6f);
+    }
+
+    @Test
+    public void multiplyIsIdentityNeutral() {
+        float[] t = Mat4.translation(1, 2, 3);
+        assertArrayEquals(t, Mat4.multiply(Mat4.identity(), t), 1e-6f);
+        assertArrayEquals(t, Mat4.multiply(t, Mat4.identity()), 1e-6f);
+    }
+
+    @Test
+    public void rotationZ90MapsXAxisToYAxis() {
+        float[] m = Mat4.rotationZ((float) (Math.PI / 2));
+        float[] v = Mat4.transform(m, 1, 0, 0, 1);
+        assertEquals(0f, v[0], 1e-6f);
+        assertEquals(1f, v[1], 1e-6f);
+    }
+
+    @Test
+    public void perspectiveHasExpectedDiagonalStructure() {
+        float[] p = Mat4.perspective((float) Math.toRadians(60), 1.0f, 1f, 100f);
+        // column-major: focal length on [0] and [5], -1 in the w-from-z slot [11]
+        float f = (float) (1.0 / Math.tan(Math.toRadians(60) / 2));
+        assertEquals(f, p[0], 1e-5f);
+        assertEquals(f, p[5], 1e-5f);
+        assertEquals(-1f, p[11], 1e-6f);
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=Mat4Test test`
+Expected: FAIL (`Mat4` does not exist).
+
+- [ ] **Step 3: Implement**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+/**
+ * Minimal column-major 4x4 float matrix helpers, layout-compatible with OpenGL uniform uploads
+ * (element index = column*4 + row).
+ */
+public final class Mat4 {
+
+    private Mat4() {}
+
+    public static float[] identity() {
+        float[] m = new float[16];
+        m[0] = m[5] = m[10] = m[15] = 1f;
+        return m;
+    }
+
+    public static float[] translation(float x, float y, float z) {
+        float[] m = identity();
+        m[12] = x;
+        m[13] = y;
+        m[14] = z;
+        return m;
+    }
+
+    /** Returns a * b (column-major). */
+    public static float[] multiply(float[] a, float[] b) {
+        float[] r = new float[16];
+        for (int col = 0; col < 4; col++) {
+            for (int row = 0; row < 4; row++) {
+                float sum = 0f;
+                for (int k = 0; k < 4; k++) {
+                    sum += a[k * 4 + row] * b[col * 4 + k];
+                }
+                r[col * 4 + row] = sum;
+            }
+        }
+        return r;
+    }
+
+    /** Returns m * (x,y,z,w) as a length-4 array. */
+    public static float[] transform(float[] m, float x, float y, float z, float w) {
+        return new float[] {
+            m[0] * x + m[4] * y + m[8]  * z + m[12] * w,
+            m[1] * x + m[5] * y + m[9]  * z + m[13] * w,
+            m[2] * x + m[6] * y + m[10] * z + m[14] * w,
+            m[3] * x + m[7] * y + m[11] * z + m[15] * w
+        };
+    }
+
+    public static float[] rotationX(float rad) {
+        float c = (float) Math.cos(rad);
+        float s = (float) Math.sin(rad);
+        float[] m = identity();
+        m[5] = c;  m[9]  = -s;
+        m[6] = s;  m[10] = c;
+        return m;
+    }
+
+    public static float[] rotationZ(float rad) {
+        float c = (float) Math.cos(rad);
+        float s = (float) Math.sin(rad);
+        float[] m = identity();
+        m[0] = c;  m[4] = -s;
+        m[1] = s;  m[5] = c;
+        return m;
+    }
+
+    /** Right-handed perspective projection (camera looks down -Z). */
+    public static float[] perspective(float fovyRad, float aspect, float near, float far) {
+        float f = (float) (1.0 / Math.tan(fovyRad / 2.0));
+        float[] m = new float[16];
+        m[0] = f / aspect;
+        m[5] = f;
+        m[10] = (far + near) / (near - far);
+        m[11] = -1f;
+        m[14] = (2f * far * near) / (near - far);
+        return m;
+    }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=Mat4Test test`
+Expected: PASS (Tests run: 5).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/Mat4.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/test/java/de/hft/stuttgart/citydoctor2/gui/gl/Mat4Test.java
+git commit -m "Add column-major Mat4 matrix helpers"
+```
+
+---
+
+### Task 6: `OrbitCamera` (view-projection + interaction state)
+
+Replicates the legacy camera state from `MainWindow`: orbit via a Z rotation (`cameraXRot`) and an X
+rotation (`cameraYRot`) applied to the world, zoom via `translateZ` (negative = farther), pan via
+`translateX/Y`, and `zoomOutForBoundingBox` distance using the same `tan(30°/2)` math.
+
+> **Note on sign/handedness:** exact pixel-parity with JavaFX is not required (the spec only needs equivalent
+> orbit/zoom/pan behavior). The unit tests below assert mathematical invariants (focus point lands at the
+> NDC center, zooming preserves centering, aspect affects X). Final rotation *direction* (drag sign) is
+> confirmed during manual verification in Phase 6 and adjusted by flipping the relevant delta signs in the
+> input handlers (Task 16), not by changing this class.
+
+**Files:**
+- Create: `.../gui/gl/OrbitCamera.java`
+- Test: `.../test/.../gui/gl/OrbitCameraTest.java`
+
+- [ ] **Step 1: Write the failing test**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+import org.junit.Test;
+
+public class OrbitCameraTest {
+
+    private static float[] ndc(OrbitCamera cam, float x, float y, float z) {
+        float[] clip = Mat4.transform(cam.viewProjection(), x, y, z, 1);
+        return new float[]{clip[0] / clip[3], clip[1] / clip[3], clip[2] / clip[3]};
+    }
+
+    @Test
+    public void focusPointProjectsToScreenCentre() {
+        OrbitCamera cam = new OrbitCamera();
+        cam.setAspect(1.0f);
+        cam.zoomOutForBoundingBox(50.0); // sets a sensible distance
+        float[] p = ndc(cam, 0, 0, 0);
+        assertEquals(0f, p[0], 1e-4f);
+        assertEquals(0f, p[1], 1e-4f);
+        assertTrue("origin in front of camera (within clip)", p[2] > -1f && p[2] < 1f);
+    }
+
+    @Test
+    public void zoomingKeepsFocusCentredButChangesDepth() {
+        OrbitCamera cam = new OrbitCamera();
+        cam.setAspect(1.0f);
+        cam.zoomOutForBoundingBox(50.0);
+        float depthBefore = ndc(cam, 0, 0, 0)[2];
+        cam.zoom(1.5); // farther
+        float[] p = ndc(cam, 0, 0, 0);
+        assertEquals(0f, p[0], 1e-4f);
+        assertEquals(0f, p[1], 1e-4f);
+        assertTrue("depth changes when zooming", Math.abs(p[2] - depthBefore) > 1e-4f);
+    }
+
+    @Test
+    public void resetRestoresInitialDistanceAndAngles() {
+        OrbitCamera cam = new OrbitCamera();
+        cam.setAspect(1.0f);
+        cam.orbit(40, 25);
+        cam.pan(10, -5);
+        cam.zoom(2.0);
+        cam.reset();
+        float[] before = cam.viewProjection();
+        OrbitCamera fresh = new OrbitCamera();
+        fresh.setAspect(1.0f);
+        org.junit.Assert.assertArrayEquals(fresh.viewProjection(), before, 1e-5f);
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=OrbitCameraTest test`
+Expected: FAIL (`OrbitCamera` does not exist).
+
+- [ ] **Step 3: Implement**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+/**
+ * Orbit camera reproducing the legacy JavaFX interaction model: world is rotated about Z then X, the
+ * camera sits at {@code distance} along -Z (negative distance = farther away) and pans in X/Y.
+ */
+public class OrbitCamera {
+
+    private static final double INITIAL_AZIMUTH = 120.0; // legacy CAMERA_INITIAL_Y_ANGLE (Z rotation)
+    private static final double INITIAL_ELEVATION = 20.0; // legacy CAMERA_INITIAL_X_ANGLE (X rotation)
+    private static final double INITIAL_DISTANCE = 100.0;
+    private static final double FOVY_RAD = Math.toRadians(30);
+    private static final float NEAR = 0.1f;
+    private static final float FAR = 10000f;
+
+    private double azimuthDeg = INITIAL_AZIMUTH;
+    private double elevationDeg = INITIAL_ELEVATION;
+    private double distance = INITIAL_DISTANCE; // positive magnitude; camera at z = -distance
+    private double panX = 0;
+    private double panY = 0;
+    private float aspect = 1.0f;
+
+    public void setAspect(float aspect) {
+        if (aspect > 0) {
+            this.aspect = aspect;
+        }
+    }
+
+    public void orbit(double deltaAzimuthDeg, double deltaElevationDeg) {
+        azimuthDeg += deltaAzimuthDeg;
+        elevationDeg += deltaElevationDeg;
+    }
+
+    public void pan(double dx, double dy) {
+        panX += dx;
+        panY += dy;
+    }
+
+    /** factor &gt; 1 moves farther, &lt; 1 moves closer. */
+    public void zoom(double factor) {
+        distance *= factor;
+    }
+
+    /** Matches legacy MainWindow.zoomOutForBoundingBox distance computation. */
+    public void zoomOutForBoundingBox(double diagonalLength) {
+        double longestSide = diagonalLength * 0.4;
+        distance = longestSide / Math.tan(FOVY_RAD / 2.0);
+        panX = 0;
+        panY = 0;
+    }
+
+    public void reset() {
+        azimuthDeg = INITIAL_AZIMUTH;
+        elevationDeg = INITIAL_ELEVATION;
+        distance = INITIAL_DISTANCE;
+        panX = 0;
+        panY = 0;
+    }
+
+    public double distance() { return distance; }
+
+    /** Combined projection * view * model-rotation, column-major, ready for a GL uniform. */
+    public float[] viewProjection() {
+        float[] proj = Mat4.perspective((float) FOVY_RAD, aspect, NEAR, FAR);
+        // camera transform: pan in screen plane, pull back by distance along -Z
+        float[] view = Mat4.translation((float) -panX, (float) -panY, (float) -distance);
+        float[] rot = Mat4.multiply(
+                Mat4.rotationX((float) Math.toRadians(elevationDeg)),
+                Mat4.rotationZ((float) Math.toRadians(azimuthDeg)));
+        return Mat4.multiply(proj, Mat4.multiply(view, rot));
+    }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=OrbitCameraTest test`
+Expected: PASS (Tests run: 3).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/OrbitCamera.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/test/java/de/hft/stuttgart/citydoctor2/gui/gl/OrbitCameraTest.java
+git commit -m "Add OrbitCamera reproducing legacy view interaction"
+```
+
+---
+
+### Task 7: `MeshAccumulator` (triangles → interleaved arrays)
+
+Accumulates per-vertex `position` (recentered), `color` (rgb floats), and `id` (per vertex), with one
+entry per triangle corner (no cross-triangle dedup — keeps triangle→metadata mapping trivial for filtering).
+
+**Files:**
+- Create: `.../gui/gl/MeshAccumulator.java`
+- Test: `.../test/.../gui/gl/MeshAccumulatorTest.java`
+
+- [ ] **Step 1: Write the failing test**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import de.hft.stuttgart.citydoctor2.math.Triangle3d;
+import de.hft.stuttgart.citydoctor2.math.Vector3d;
+import org.junit.Test;
+
+public class MeshAccumulatorTest {
+
+    @Test
+    public void emitsNineFloatsAndThreeIdsPerTriangleRecentered() {
+        MeshAccumulator acc = new MeshAccumulator(new Vector3d(1, 0, 0));
+        Triangle3d t = new Triangle3d(
+                new Vector3d(1, 0, 0), new Vector3d(2, 0, 0), new Vector3d(1, 1, 0));
+        acc.addTriangle(t, 7, 0.5f, 0.25f, 0.125f);
+
+        assertEquals(3, acc.vertexCount());
+        // positions recentred by (1,0,0):
+        assertArrayEquals(new float[]{0,0,0, 1,0,0, 0,1,0}, acc.positions(), 1e-6f);
+        // color repeated per vertex:
+        assertArrayEquals(new float[]{0.5f,0.25f,0.125f, 0.5f,0.25f,0.125f, 0.5f,0.25f,0.125f},
+                acc.colors(), 1e-6f);
+        assertArrayEquals(new int[]{7, 7, 7}, acc.ids());
+    }
+
+    @Test
+    public void accumulatesMultipleTriangles() {
+        MeshAccumulator acc = new MeshAccumulator(new Vector3d(0, 0, 0));
+        Triangle3d t = new Triangle3d(
+                new Vector3d(0, 0, 0), new Vector3d(1, 0, 0), new Vector3d(0, 1, 0));
+        acc.addTriangle(t, 1, 1, 1, 1);
+        acc.addTriangle(t, 2, 0, 0, 0);
+        assertEquals(6, acc.vertexCount());
+        assertEquals(18, acc.positions().length);
+        assertArrayEquals(new int[]{1, 1, 1, 2, 2, 2}, acc.ids());
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=MeshAccumulatorTest test`
+Expected: FAIL (`MeshAccumulator` does not exist).
+
+- [ ] **Step 3: Implement**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import de.hft.stuttgart.citydoctor2.math.Triangle3d;
+import de.hft.stuttgart.citydoctor2.math.Vector3d;
+
+/**
+ * Builds interleaved-by-attribute vertex arrays from triangles. Vertices are stored per triangle corner
+ * (3 per triangle) so a triangle's vertices occupy a contiguous, predictable range — which lets the
+ * draw index set be built by triangle without dedup bookkeeping.
+ */
+public class MeshAccumulator {
+
+    private final Vector3d center;
+    private final FloatList positions = new FloatList();
+    private final FloatList colors = new FloatList();
+    private final IntList ids = new IntList();
+    private int vertexCount;
+
+    public MeshAccumulator(Vector3d center) {
+        this.center = center;
+    }
+
+    public void addTriangle(Triangle3d t, int id, float r, float g, float b) {
+        addVertex(t.getP1(), id, r, g, b);
+        addVertex(t.getP2(), id, r, g, b);
+        addVertex(t.getP3(), id, r, g, b);
+    }
+
+    private void addVertex(Vector3d p, int id, float r, float g, float b) {
+        positions.add((float) (p.getX() - center.getX()),
+                      (float) (p.getY() - center.getY()),
+                      (float) (p.getZ() - center.getZ()));
+        colors.add(r, g, b);
+        ids.add(id);
+        vertexCount++;
+    }
+
+    public int vertexCount() { return vertexCount; }
+
+    public float[] positions() { return positions.toArray(); }
+
+    public float[] colors() { return colors.toArray(); }
+
+    public int[] ids() { return ids.toArray(); }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=MeshAccumulatorTest test`
+Expected: PASS (Tests run: 2).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/MeshAccumulator.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/test/java/de/hft/stuttgart/citydoctor2/gui/gl/MeshAccumulatorTest.java
+git commit -m "Add MeshAccumulator building interleaved vertex arrays"
+```
+
+---
+
+### Task 8: `TriangleMeta` + `IndexSetBuilder` (filter → draw index set)
+
+Per-triangle metadata plus the logic that, given active filters, produces the `int[]` element index set
+(triangle vertex indices) to draw. Triangle `i` occupies vertices `3i, 3i+1, 3i+2`.
+
+**Files:**
+- Create: `.../gui/gl/TriangleMeta.java`
+- Create: `.../gui/gl/IndexSetBuilder.java`
+- Test: `.../test/.../gui/gl/IndexSetBuilderTest.java`
+
+- [ ] **Step 1: Write the failing test**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import static org.junit.Assert.assertArrayEquals;
+import java.util.Arrays;
+import java.util.List;
+import java.util.function.Predicate;
+import org.junit.Test;
+
+public class IndexSetBuilderTest {
+
+    @Test
+    public void includesOnlyTrianglesMatchingThePredicate() {
+        // 3 triangles; meta carries an int "group" we filter on
+        List<TriangleMeta> metas = Arrays.asList(
+                new TriangleMeta(0, null, 1, false),
+                new TriangleMeta(1, null, 2, false),
+                new TriangleMeta(2, null, 1, false));
+        Predicate<TriangleMeta> onlyGroup1 = m -> m.lod() == 1;
+        int[] indices = IndexSetBuilder.build(metas, onlyGroup1);
+        // triangles 0 and 2 -> vertices [0,1,2] and [6,7,8]
+        assertArrayEquals(new int[]{0, 1, 2, 6, 7, 8}, indices);
+    }
+
+    @Test
+    public void emptyWhenNothingMatches() {
+        List<TriangleMeta> metas = Arrays.asList(new TriangleMeta(0, null, 1, false));
+        int[] indices = IndexSetBuilder.build(metas, m -> false);
+        assertArrayEquals(new int[]{}, indices);
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=IndexSetBuilderTest test`
+Expected: FAIL (`TriangleMeta` / `IndexSetBuilder` do not exist).
+
+- [ ] **Step 3: Implement**
+
+```java
+// TriangleMeta.java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import de.hft.stuttgart.citydoctor2.datastructure.Polygon;
+
+/**
+ * Metadata for one triangle in the global buffer.
+ * @param triangleIndex index of this triangle (vertices are 3*triangleIndex .. +2)
+ * @param polygon       source polygon (for picking/highlight resolution); may be null in tests
+ * @param lod           LOD ordinal (Lod.ordinal()) of the owning geometry
+ * @param roof          true if the triangle belongs to a ROOF boundary surface
+ */
+public record TriangleMeta(int triangleIndex, Polygon polygon, int lod, boolean roof) {}
+```
+
+```java
+// IndexSetBuilder.java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import java.util.List;
+import java.util.function.Predicate;
+
+/** Builds the element index set (triangle vertex indices) for the triangles passing the filter. */
+public final class IndexSetBuilder {
+
+    private IndexSetBuilder() {}
+
+    public static int[] build(List<TriangleMeta> metas, Predicate<TriangleMeta> include) {
+        IntList out = new IntList();
+        for (TriangleMeta m : metas) {
+            if (include.test(m)) {
+                int base = m.triangleIndex() * 3;
+                out.add(base);
+                out.add(base + 1);
+                out.add(base + 2);
+            }
+        }
+        return out.toArray();
+    }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=IndexSetBuilderTest test`
+Expected: PASS (Tests run: 2).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/TriangleMeta.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/IndexSetBuilder.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/test/java/de/hft/stuttgart/citydoctor2/gui/gl/IndexSetBuilderTest.java
+git commit -m "Add TriangleMeta and IndexSetBuilder for filter-driven draw sets"
+```
+
+---
+
+### Task 9: `SceneData` (immutable result of a build)
+
+Plain container produced by the builder and consumed by the GL layer. No logic worth TDD beyond a
+construction smoke test.
+
+**Files:**
+- Create: `.../gui/gl/SceneData.java`
+- Test: `.../test/.../gui/gl/SceneDataTest.java`
+
+- [ ] **Step 1: Write the failing test**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertSame;
+import java.util.List;
+import org.junit.Test;
+
+public class SceneDataTest {
+
+    @Test
+    public void exposesItsBuffersAndRegistry() {
+        float[] pos = {0,0,0, 1,0,0, 0,1,0};
+        float[] col = {1,1,1, 1,1,1, 1,1,1};
+        int[] ids = {1,1,1};
+        PickRegistry reg = new PickRegistry();
+        List<TriangleMeta> metas = List.of(new TriangleMeta(0, null, 2, false));
+        SceneData data = new SceneData(pos, col, ids, metas, reg, new double[]{5, 6, 7});
+
+        assertSame(pos, data.positions());
+        assertEquals(1, data.triangleMetas().size());
+        assertEquals(6.0, data.center()[1], 0.0);
+        assertSame(reg, data.pickRegistry());
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=SceneDataTest test`
+Expected: FAIL (`SceneData` does not exist).
+
+- [ ] **Step 3: Implement**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import java.util.List;
+
+/** Immutable CPU-side result of building the scene; uploaded to the GPU by the GL layer. */
+public class SceneData {
+
+    private final float[] positions;
+    private final float[] colors;
+    private final int[] ids;
+    private final List<TriangleMeta> triangleMetas;
+    private final PickRegistry pickRegistry;
+    private final double[] center;
+
+    public SceneData(float[] positions, float[] colors, int[] ids,
+                     List<TriangleMeta> triangleMetas, PickRegistry pickRegistry, double[] center) {
+        this.positions = positions;
+        this.colors = colors;
+        this.ids = ids;
+        this.triangleMetas = triangleMetas;
+        this.pickRegistry = pickRegistry;
+        this.center = center;
+    }
+
+    public float[] positions() { return positions; }
+    public float[] colors() { return colors; }
+    public int[] ids() { return ids; }
+    public List<TriangleMeta> triangleMetas() { return triangleMetas; }
+    public PickRegistry pickRegistry() { return pickRegistry; }
+    public double[] center() { return center; }
+    public int triangleCount() { return triangleMetas.size(); }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=SceneDataTest test`
+Expected: PASS (Tests run: 1).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/SceneData.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/test/java/de/hft/stuttgart/citydoctor2/gui/gl/SceneDataTest.java
+git commit -m "Add SceneData container for built scene buffers"
+```
+
+---
+
+### Task 10: `SceneBuilder` (model/polygons → `SceneData`)
+
+Replaces `TriangulatedGeometry`. Iterates polygons, tesselates, bakes shade color (Task 4), assigns picking
+ids (Task 3), accumulates vertices (Task 7), records `TriangleMeta` (Task 8), and recenters by the bounding
+center. Runs on a worker thread (never the GL thread).
+
+Picking-id allocation uses one `PickRegistry` per build; each polygon registers once and all its triangles
+share that id (matches "click polygon → select polygon").
+
+**Files:**
+- Create: `.../gui/gl/SceneBuilder.java`
+- Test: `.../test/.../gui/gl/SceneBuilderTest.java`
+
+- [ ] **Step 1: Write the failing test**
+
+This test builds from a small list of polygons using the project's existing `Polygon` API. Use the same
+GML fixture the module already ships (`src/test/resources/SimpleSolid_SrefBS-GE-gml-LR-0001-T0001.gml`) by
+loading it and collecting its concrete polygons.
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+
+import de.hft.stuttgart.citydoctor2.datastructure.CityDoctorModel;
+import de.hft.stuttgart.citydoctor2.datastructure.ConcretePolygon;
+import de.hft.stuttgart.citydoctor2.datastructure.Geometry;
+import de.hft.stuttgart.citydoctor2.datastructure.Polygon;
+import de.hft.stuttgart.citydoctor2.parser.CityGmlParser;
+import java.util.ArrayList;
+import java.util.List;
+import javafx.scene.paint.Color;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+public class SceneBuilderTest {
+
+    private static List<Polygon> polygons;
+
+    @BeforeClass
+    public static void loadFixture() throws Exception {
+        // NOTE: confirm the exact CityGmlParser entry point during implementation (Step 3 notes).
+        CityDoctorModel model = CityGmlParser.parseCityGmlFile(
+                "src/test/resources/SimpleSolid_SrefBS-GE-gml-LR-0001-T0001.gml", 8);
+        polygons = new ArrayList<>();
+        model.getBuildings().forEach(b -> {
+            for (Geometry g : b.getGeometries()) {
+                for (Polygon p : g.getPolygons()) {
+                    if (!p.isLink()) {
+                        polygons.add(p);
+                    }
+                }
+            }
+        });
+        assertTrue("fixture should contain polygons", !polygons.isEmpty());
+    }
+
+    @Test
+    public void buildsConsistentBufferLengths() {
+        SceneData data = SceneBuilder.fromPolygons(polygons, Color.WHITE);
+        int vertices = data.positions().length / 3;
+        assertEquals(vertices * 3, data.colors().length);
+        assertEquals(vertices, data.ids().length);
+        assertEquals(vertices, data.triangleCount() * 3);
+    }
+
+    @Test
+    public void everyPolygonGetsAPickingIdResolvingToAPolygon() {
+        SceneData data = SceneBuilder.fromPolygons(polygons, Color.WHITE);
+        // each id in the id buffer resolves to a Polygon
+        for (int id : data.ids()) {
+            assertTrue(data.pickRegistry().resolve(id) instanceof Polygon);
+        }
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=SceneBuilderTest test`
+Expected: FAIL (`SceneBuilder` does not exist). If the `CityGmlParser` entry point differs, adjust the
+fixture-loading line — confirm the signature via
+`grep -rn "public static .*parse" CityDoctorParent/CityDoctorModel/src/main/java/.../parser/CityGmlParser.java`.
+
+- [ ] **Step 3: Implement**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import de.hft.stuttgart.citydoctor2.datastructure.CityDoctorModel;
+import de.hft.stuttgart.citydoctor2.datastructure.CityObject;
+import de.hft.stuttgart.citydoctor2.datastructure.Geometry;
+import de.hft.stuttgart.citydoctor2.datastructure.Lod;
+import de.hft.stuttgart.citydoctor2.datastructure.Polygon;
+import de.hft.stuttgart.citydoctor2.math.Triangle3d;
+import de.hft.stuttgart.citydoctor2.math.Vector3d;
+import de.hft.stuttgart.citydoctor2.tesselation.TesselatedPolygon;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import javafx.scene.paint.Color;
+
+/**
+ * Builds {@link SceneData} from model polygons: tesselate, bake shade colour, assign picking ids,
+ * accumulate vertices and per-triangle metadata, recentre by the bounding-box centre.
+ * Intended to run on a worker thread.
+ */
+public final class SceneBuilder {
+
+    private SceneBuilder() {}
+
+    public static SceneData fromPolygons(Collection<? extends Polygon> polygons, Color baseColor) {
+        return build(polygons, baseColor, Lod.LOD2.ordinal(), false);
+    }
+
+    /** General entry: caller supplies polygons already chosen, plus their lod/roof attributes. */
+    public static SceneData build(Collection<? extends Polygon> polygons, Color baseColor,
+                                  int lod, boolean roof) {
+        Vector3d center = findCenter(polygons);
+        MeshAccumulator acc = new MeshAccumulator(center);
+        PickRegistry registry = new PickRegistry();
+        List<TriangleMeta> metas = new ArrayList<>();
+        int triangleIndex = 0;
+
+        for (Polygon p : polygons) {
+            Color base = chooseBase(p, baseColor);
+            Color shaded = ShadeColor.shade(p.calculateNormalNormalized(), base);
+            float r = (float) shaded.getRed();
+            float g = (float) shaded.getGreen();
+            float b = (float) shaded.getBlue();
+            int id = registry.register(p);
+
+            TesselatedPolygon tp = p.tesselate();
+            for (Triangle3d t : tp.getTriangles()) {
+                acc.addTriangle(t, id, r, g, b);
+                metas.add(new TriangleMeta(triangleIndex++, p, lod, roof));
+            }
+        }
+
+        double[] centerArr = {center.getX(), center.getY(), center.getZ()};
+        return new SceneData(acc.positions(), acc.colors(), acc.ids(), metas, registry, centerArr);
+    }
+
+    private static Color chooseBase(Polygon p, Color fallback) {
+        Color rc = p.getRenderColor();
+        if (rc != null && !rc.equals(Color.WHITE)) {
+            return rc;
+        }
+        return fallback;
+    }
+
+    private static Vector3d findCenter(Collection<? extends Polygon> polygons) {
+        double xMin = Double.MAX_VALUE, yMin = Double.MAX_VALUE, zMin = Double.MAX_VALUE;
+        double xMax = -Double.MAX_VALUE, yMax = -Double.MAX_VALUE, zMax = -Double.MAX_VALUE;
+        for (Polygon p : polygons) {
+            for (Vector3d v : p.getExteriorRing().getVertices()) {
+                xMin = Math.min(xMin, v.getX()); xMax = Math.max(xMax, v.getX());
+                yMin = Math.min(yMin, v.getY()); yMax = Math.max(yMax, v.getY());
+                zMin = Math.min(zMin, v.getZ()); zMax = Math.max(zMax, v.getZ());
+            }
+        }
+        if (xMin > xMax) { // empty
+            return new Vector3d(0, 0, 0);
+        }
+        return new Vector3d((xMax - xMin) / 2 + xMin, (yMax - yMin) / 2 + yMin, (zMax - zMin) / 2 + zMin);
+    }
+}
+```
+
+> Implementation note: `getExteriorRing().getVertices()` returns `Vertex` which extends `Vector3d`
+> (confirm with `grep -n "class Vertex" .../datastructure/Vertex.java`); if not, adapt the accessor.
+> A full model-driven builder (iterating `CityDoctorModel` features with per-feature colours and LOD,
+> mirroring the legacy `TriangulatedGeometry.of(model, filters)`) is added when wiring the `Renderer`
+> in Task 15; this task delivers the polygon-level core the `Renderer` will call.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false -Dtest=SceneBuilderTest test`
+Expected: PASS (Tests run: 2).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/SceneBuilder.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/test/java/de/hft/stuttgart/citydoctor2/gui/gl/SceneBuilderTest.java
+git commit -m "Add SceneBuilder turning polygons into SceneData"
+```
+
+---
+
+## Phase 2 — GL infrastructure (verify by running)
+
+These tasks touch the live GL context and openglfx; they can't be unit-tested headlessly, so each ends
+with a **build + run + observe** verification and a commit. Keep a small CityGML file handy for runs.
+
+### Task 11: Confirm JOGL natives & openglfx load (pre-flight)
+
+**Files:**
+- Modify: `CityDoctorParent/Extensions/CityDoctorGUI/pom.xml` (only if natives are missing)
+
+- [ ] **Step 1: Verify the JOGL runtime + natives are on the GUI classpath**
+
+Run (from `CityDoctorParent`):
+`mvn -pl Extensions/CityDoctorGUI -am dependency:tree -Dincludes=org.jogamp.jogl,org.jogamp.gluegen,com.huskerdev`
+Expected: `openglfx-jogl`, `jogl-all` (or `jogl-all-main`), and `gluegen-rt` appear. If `jogl-all` natives
+for win/linux are absent, add to `pom.xml` dependencies:
+
+```xml
+<dependency>
+    <groupId>org.jogamp.jogl</groupId>
+    <artifactId>jogl-all-main</artifactId>
+</dependency>
+<dependency>
+    <groupId>org.jogamp.gluegen</groupId>
+    <artifactId>gluegen-rt-main</artifactId>
+</dependency>
+```
+(Version is managed by the parent `pom.xml` `dependencyManagement` — see `CityDoctorParent/pom.xml:169,179`.)
+
+- [ ] **Step 2: Minimal canvas smoke test**
+
+Temporarily add a `main` to a scratch class (or a JUnit test guarded by `Assume.assumeFalse(GraphicsEnvironment.isHeadless())`) that constructs `new GLCanvas(new JOGLExecutor(), GLProfile.CORE)` inside a JavaFX `Application.start`, adds it to a `Scene`, and logs from an `addOnInitEvent` handler.
+
+Run the existing app entry instead if simpler:
+`mvn -pl Extensions/CityDoctorGUI -am -Pcreate-binaries=false exec:java -Dexec.mainClass=de.hft.stuttgart.citydoctor2.gui.MainWindow`
+Expected at this stage: app still launches with the current JavaFX view (no regression). The smoke goal is
+only to confirm openglfx classes load without `UnsatisfiedLinkError`.
+
+- [ ] **Step 3: Commit (only if pom changed)**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/pom.xml
+git commit -m "Ensure JOGL runtime natives available for GUI OpenGL view"
+```
+
+---
+
+### Task 12: Shader sources + `ShaderProgram` helper
+
+**Files:**
+- Create: `.../resources/de/hft/stuttgart/citydoctor2/gui/gl/scene.vert`
+- Create: `.../resources/de/hft/stuttgart/citydoctor2/gui/gl/scene.frag`
+- Create: `.../resources/de/hft/stuttgart/citydoctor2/gui/gl/pick.vert`
+- Create: `.../resources/de/hft/stuttgart/citydoctor2/gui/gl/pick.frag`
+- Create: `.../gui/gl/ShaderProgram.java`
+
+- [ ] **Step 1: Write `scene.vert`**
+
+```glsl
+#version 330 core
+layout(location = 0) in vec3 aPos;
+layout(location = 1) in vec3 aColor;
+layout(location = 2) in int  aId;
+uniform mat4 uMVP;
+uniform int  uSelectedId;
+out vec3 vColor;
+flat out int vSelected;
+void main() {
+    gl_Position = uMVP * vec4(aPos, 1.0);
+    vColor = aColor;
+    vSelected = (aId == uSelectedId) ? 1 : 0;
+}
+```
+
+- [ ] **Step 2: Write `scene.frag`**
+
+```glsl
+#version 330 core
+in vec3 vColor;
+flat in int vSelected;
+out vec4 fragColor;
+void main() {
+    vec3 c = vColor;
+    if (vSelected == 1) {
+        c = mix(c, vec3(1.0, 0.0, 0.0), 0.6);
+    }
+    fragColor = vec4(c, 1.0);
+}
+```
+
+- [ ] **Step 3: Write `pick.vert`**
+
+```glsl
+#version 330 core
+layout(location = 0) in vec3 aPos;
+layout(location = 2) in int  aId;
+uniform mat4 uMVP;
+flat out int vId;
+void main() {
+    gl_Position = uMVP * vec4(aPos, 1.0);
+    vId = aId;
+}
+```
+
+- [ ] **Step 4: Write `pick.frag`** (must mirror `PickingCodec`: id low byte → red)
+
+```glsl
+#version 330 core
+flat in int vId;
+out vec4 fragColor;
+void main() {
+    int id = vId;
+    float r = float( id        & 0xFF) / 255.0;
+    float g = float((id >> 8)  & 0xFF) / 255.0;
+    float b = float((id >> 16) & 0xFF) / 255.0;
+    fragColor = vec4(r, g, b, 1.0);
+}
+```
+
+- [ ] **Step 5: Implement `ShaderProgram`**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import com.jogamp.opengl.GL3;
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.io.UncheckedIOException;
+import java.nio.charset.StandardCharsets;
+import java.util.stream.Collectors;
+
+/** Compiles and links a GLSL program from classpath resources next to this class. */
+public class ShaderProgram {
+
+    private final int program;
+
+    public ShaderProgram(GL3 gl, String vertexResource, String fragmentResource) {
+        int vs = compile(gl, GL3.GL_VERTEX_SHADER, read(vertexResource));
+        int fs = compile(gl, GL3.GL_FRAGMENT_SHADER, read(fragmentResource));
+        program = gl.glCreateProgram();
+        gl.glAttachShader(program, vs);
+        gl.glAttachShader(program, fs);
+        gl.glLinkProgram(program);
+        checkLink(gl, program);
+        gl.glDeleteShader(vs);
+        gl.glDeleteShader(fs);
+    }
+
+    public void use(GL3 gl) { gl.glUseProgram(program); }
+
+    public int uniform(GL3 gl, String name) { return gl.glGetUniformLocation(program, name); }
+
+    public void dispose(GL3 gl) { gl.glDeleteProgram(program); }
+
+    private static int compile(GL3 gl, int type, String src) {
+        int shader = gl.glCreateShader(type);
+        gl.glShaderSource(shader, 1, new String[]{src}, new int[]{src.length()}, 0);
+        gl.glCompileShader(shader);
+        int[] status = new int[1];
+        gl.glGetShaderiv(shader, GL3.GL_COMPILE_STATUS, status, 0);
+        if (status[0] == 0) {
+            throw new IllegalStateException("Shader compile failed: " + infoLog(gl, shader, true));
+        }
+        return shader;
+    }
+
+    private static void checkLink(GL3 gl, int program) {
+        int[] status = new int[1];
+        gl.glGetProgramiv(program, GL3.GL_LINK_STATUS, status, 0);
+        if (status[0] == 0) {
+            throw new IllegalStateException("Program link failed: " + infoLog(gl, program, false));
+        }
+    }
+
+    private static String infoLog(GL3 gl, int handle, boolean shader) {
+        int[] len = new int[1];
+        if (shader) {
+            gl.glGetShaderiv(handle, GL3.GL_INFO_LOG_LENGTH, len, 0);
+        } else {
+            gl.glGetProgramiv(handle, GL3.GL_INFO_LOG_LENGTH, len, 0);
+        }
+        byte[] log = new byte[Math.max(1, len[0])];
+        if (shader) {
+            gl.glGetShaderInfoLog(handle, log.length, new int[1], 0, log, 0);
+        } else {
+            gl.glGetProgramInfoLog(handle, log.length, new int[1], 0, log, 0);
+        }
+        return new String(log, StandardCharsets.UTF_8);
+    }
+
+    private static String read(String resource) {
+        try (InputStream in = ShaderProgram.class.getResourceAsStream(resource)) {
+            if (in == null) {
+                throw new IllegalStateException("Shader resource not found: " + resource);
+            }
+            try (BufferedReader r = new BufferedReader(new InputStreamReader(in, StandardCharsets.UTF_8))) {
+                return r.lines().collect(Collectors.joining("\n"));
+            }
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+    }
+}
+```
+
+- [ ] **Step 6: Build to confirm it compiles**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DskipTests compile`
+Expected: BUILD SUCCESS. (Runtime shader compilation is exercised in Task 13.)
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/resources/de/hft/stuttgart/citydoctor2/gui/gl/ \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/ShaderProgram.java
+git commit -m "Add scene/pick shaders and ShaderProgram compiler"
+```
+
+---
+
+### Task 13: `GlScene` (VAO/VBO/EBO upload + draw)
+
+Owns the global VBO and index buffer; uploads `SceneData`; draws the current index set with the scene or
+pick program. GL-thread only.
+
+**Files:**
+- Create: `.../gui/gl/GlScene.java`
+
+- [ ] **Step 1: Implement**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import com.jogamp.opengl.GL;
+import com.jogamp.opengl.GL3;
+import java.nio.ByteBuffer;
+import java.nio.ByteOrder;
+import java.nio.FloatBuffer;
+import java.nio.IntBuffer;
+
+/** GPU resources for the global scene mesh. Single VBO (pos+color+id), one index buffer redrawn per frame. */
+public class GlScene {
+
+    private int vao = 0;
+    private int vboPos;
+    private int vboColor;
+    private int vboId;
+    private int ebo;
+    private int indexCount;
+    private boolean uploaded;
+
+    public void upload(GL3 gl, SceneData data) {
+        if (!uploaded) {
+            int[] ids = new int[3];
+            gl.glGenVertexArrays(1, ids, 0);
+            vao = ids[0];
+            int[] buffers = new int[4];
+            gl.glGenBuffers(4, buffers, 0);
+            vboPos = buffers[0];
+            vboColor = buffers[1];
+            vboId = buffers[2];
+            ebo = buffers[3];
+        }
+        gl.glBindVertexArray(vao);
+
+        uploadFloat(gl, vboPos, data.positions(), 0, 3);
+        uploadFloat(gl, vboColor, data.colors(), 1, 3);
+        uploadInt(gl, vboId, data.ids(), 2);
+
+        gl.glBindVertexArray(0);
+        uploaded = true;
+    }
+
+    private void uploadFloat(GL3 gl, int vbo, float[] data, int location, int components) {
+        gl.glBindBuffer(GL.GL_ARRAY_BUFFER, vbo);
+        FloatBuffer fb = toFloatBuffer(data);
+        gl.glBufferData(GL.GL_ARRAY_BUFFER, (long) data.length * Float.BYTES, fb, GL.GL_STATIC_DRAW);
+        gl.glEnableVertexAttribArray(location);
+        gl.glVertexAttribPointer(location, components, GL.GL_FLOAT, false, 0, 0L);
+    }
+
+    private void uploadInt(GL3 gl, int vbo, int[] data, int location) {
+        gl.glBindBuffer(GL.GL_ARRAY_BUFFER, vbo);
+        IntBuffer ib = toIntBuffer(data);
+        gl.glBufferData(GL.GL_ARRAY_BUFFER, (long) data.length * Integer.BYTES, ib, GL.GL_STATIC_DRAW);
+        gl.glEnableVertexAttribArray(location);
+        gl.glVertexAttribIPointer(location, 1, GL3.GL_INT, 0, 0L); // integer attribute, not normalized
+    }
+
+    /** Re-uploads which triangles to draw (element indices). Cheap; called on filter/LOD changes. */
+    public void setIndexSet(GL3 gl, int[] indices) {
+        gl.glBindVertexArray(vao);
+        gl.glBindBuffer(GL.GL_ELEMENT_ARRAY_BUFFER, ebo);
+        IntBuffer ib = toIntBuffer(indices);
+        gl.glBufferData(GL.GL_ELEMENT_ARRAY_BUFFER, (long) indices.length * Integer.BYTES, ib,
+                GL.GL_DYNAMIC_DRAW);
+        gl.glBindVertexArray(0);
+        indexCount = indices.length;
+    }
+
+    public void draw(GL3 gl) {
+        if (vao == 0 || indexCount == 0) {
+            return;
+        }
+        gl.glBindVertexArray(vao);
+        gl.glDrawElements(GL.GL_TRIANGLES, indexCount, GL.GL_UNSIGNED_INT, 0L);
+        gl.glBindVertexArray(0);
+    }
+
+    public boolean hasData() { return uploaded; }
+
+    public void dispose(GL3 gl) {
+        if (vao != 0) {
+            gl.glDeleteVertexArrays(1, new int[]{vao}, 0);
+            gl.glDeleteBuffers(4, new int[]{vboPos, vboColor, vboId, ebo}, 0);
+            vao = 0;
+            uploaded = false;
+        }
+    }
+
+    private static FloatBuffer toFloatBuffer(float[] data) {
+        ByteBuffer bb = ByteBuffer.allocateDirect(data.length * Float.BYTES).order(ByteOrder.nativeOrder());
+        FloatBuffer fb = bb.asFloatBuffer();
+        fb.put(data).flip();
+        return fb;
+    }
+
+    private static IntBuffer toIntBuffer(int[] data) {
+        ByteBuffer bb = ByteBuffer.allocateDirect(data.length * Integer.BYTES).order(ByteOrder.nativeOrder());
+        IntBuffer ib = bb.asIntBuffer();
+        ib.put(data).flip();
+        return ib;
+    }
+}
+```
+
+- [ ] **Step 2: Build to confirm it compiles**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DskipTests compile`
+Expected: BUILD SUCCESS.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/GlScene.java
+git commit -m "Add GlScene global VBO upload and indexed draw"
+```
+
+---
+
+### Task 14: `PickingFramebuffer` (off-screen id target + readback)
+
+**Files:**
+- Create: `.../gui/gl/PickingFramebuffer.java`
+
+- [ ] **Step 1: Implement**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import com.jogamp.opengl.GL;
+import com.jogamp.opengl.GL3;
+import java.nio.ByteBuffer;
+import java.nio.ByteOrder;
+
+/** Off-screen framebuffer that stores picking ids as RGBA8; supports single-pixel readback. */
+public class PickingFramebuffer {
+
+    private int fbo;
+    private int colorTex;
+    private int depthRbo;
+    private int width;
+    private int height;
+    private boolean created;
+
+    public void resize(GL3 gl, int w, int h) {
+        if (w <= 0 || h <= 0 || (w == width && h == height && created)) {
+            return;
+        }
+        dispose(gl);
+        width = w;
+        height = h;
+
+        int[] tmp = new int[1];
+        gl.glGenFramebuffers(1, tmp, 0);
+        fbo = tmp[0];
+        gl.glBindFramebuffer(GL.GL_FRAMEBUFFER, fbo);
+
+        gl.glGenTextures(1, tmp, 0);
+        colorTex = tmp[0];
+        gl.glBindTexture(GL.GL_TEXTURE_2D, colorTex);
+        gl.glTexImage2D(GL.GL_TEXTURE_2D, 0, GL.GL_RGBA8, w, h, 0, GL.GL_RGBA, GL.GL_UNSIGNED_BYTE, null);
+        gl.glTexParameteri(GL.GL_TEXTURE_2D, GL.GL_TEXTURE_MIN_FILTER, GL.GL_NEAREST);
+        gl.glTexParameteri(GL.GL_TEXTURE_2D, GL.GL_TEXTURE_MAG_FILTER, GL.GL_NEAREST);
+        gl.glFramebufferTexture2D(GL.GL_FRAMEBUFFER, GL.GL_COLOR_ATTACHMENT0, GL.GL_TEXTURE_2D, colorTex, 0);
+
+        gl.glGenRenderbuffers(1, tmp, 0);
+        depthRbo = tmp[0];
+        gl.glBindRenderbuffer(GL.GL_RENDERBUFFER, depthRbo);
+        gl.glRenderbufferStorage(GL.GL_RENDERBUFFER, GL.GL_DEPTH_COMPONENT16, w, h);
+        gl.glFramebufferRenderbuffer(GL.GL_FRAMEBUFFER, GL.GL_DEPTH_ATTACHMENT, GL.GL_RENDERBUFFER, depthRbo);
+
+        gl.glBindFramebuffer(GL.GL_FRAMEBUFFER, 0);
+        created = true;
+    }
+
+    public void bind(GL3 gl) {
+        gl.glBindFramebuffer(GL.GL_FRAMEBUFFER, fbo);
+        gl.glViewport(0, 0, width, height);
+    }
+
+    /**
+     * Reads the picking id at canvas pixel (x, y) measured from the top-left. GL's origin is bottom-left,
+     * so the row is flipped.
+     */
+    public int readId(GL3 gl, int x, int y) {
+        if (!created || x < 0 || y < 0 || x >= width || y >= height) {
+            return 0;
+        }
+        ByteBuffer buf = ByteBuffer.allocateDirect(4).order(ByteOrder.nativeOrder());
+        gl.glBindFramebuffer(GL.GL_FRAMEBUFFER, fbo);
+        gl.glReadPixels(x, height - 1 - y, 1, 1, GL.GL_RGBA, GL.GL_UNSIGNED_BYTE, buf);
+        gl.glBindFramebuffer(GL.GL_FRAMEBUFFER, 0);
+        int r = buf.get(0) & 0xFF;
+        int g = buf.get(1) & 0xFF;
+        int b = buf.get(2) & 0xFF;
+        return PickingCodec.decode(r, g, b);
+    }
+
+    public void dispose(GL3 gl) {
+        if (created) {
+            gl.glDeleteFramebuffers(1, new int[]{fbo}, 0);
+            gl.glDeleteTextures(1, new int[]{colorTex}, 0);
+            gl.glDeleteRenderbuffers(1, new int[]{depthRbo}, 0);
+            created = false;
+        }
+    }
+}
+```
+
+- [ ] **Step 2: Build to confirm it compiles**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DskipTests compile`
+Expected: BUILD SUCCESS.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/PickingFramebuffer.java
+git commit -m "Add PickingFramebuffer for color-pick readback"
+```
+
+---
+
+### Task 15: `HighlightOverlay` (dynamic marker buffer)
+
+Holds vertex markers (drawn as `GL_POINTS`) and edge markers (drawn as `GL_LINES`) for highlights, rebuilt
+when the highlight set changes. Reuses `scene.vert`/`scene.frag` (color attribute drives marker colour; id
+attribute is 0 so markers never tint as "selected"). Point size is set via `glPointSize`.
+
+**Files:**
+- Create: `.../gui/gl/HighlightOverlay.java`
+
+- [ ] **Step 1: Implement**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import com.jogamp.opengl.GL;
+import com.jogamp.opengl.GL3;
+import java.nio.ByteBuffer;
+import java.nio.ByteOrder;
+import java.nio.FloatBuffer;
+import java.nio.IntBuffer;
+
+/**
+ * Dynamic overlay for highlight markers: points for vertices, lines for edges. Positions are in the same
+ * recentred world space as the scene. Colour rides in the color attribute; id attribute is 0.
+ */
+public class HighlightOverlay {
+
+    private int pointVao;
+    private int pointPos;
+    private int pointColor;
+    private int pointId;
+    private int pointCount;
+
+    private int lineVao;
+    private int linePos;
+    private int lineColor;
+    private int lineId;
+    private int lineVertexCount;
+
+    private boolean created;
+
+    public void init(GL3 gl) {
+        int[] v = new int[2];
+        gl.glGenVertexArrays(2, v, 0);
+        pointVao = v[0];
+        lineVao = v[1];
+        int[] b = new int[6];
+        gl.glGenBuffers(6, b, 0);
+        pointPos = b[0]; pointColor = b[1]; pointId = b[2];
+        linePos = b[3]; lineColor = b[4]; lineId = b[5];
+        created = true;
+    }
+
+    /** points: xyz triplets; pointColors: rgb triplets (one per point). */
+    public void setPoints(GL3 gl, float[] points, float[] pointColors) {
+        pointCount = points.length / 3;
+        configure(gl, pointVao, pointPos, points, pointColor, pointColors, pointId, pointCount);
+    }
+
+    /** lines: xyz pairs of endpoints (6 floats per segment); lineColors: rgb per line vertex. */
+    public void setLines(GL3 gl, float[] lines, float[] lineColors) {
+        lineVertexCount = lines.length / 3;
+        configure(gl, lineVao, linePos, lines, lineColor, lineColors, lineId, lineVertexCount);
+    }
+
+    private void configure(GL3 gl, int vao, int posVbo, float[] pos, int colVbo, float[] col,
+                           int idVbo, int vertexCount) {
+        gl.glBindVertexArray(vao);
+        bindFloat(gl, posVbo, pos, 0, 3);
+        bindFloat(gl, colVbo, col, 1, 3);
+        // id attribute all zeros so overlay never matches uSelectedId
+        int[] zeros = new int[vertexCount];
+        gl.glBindBuffer(GL.GL_ARRAY_BUFFER, idVbo);
+        gl.glBufferData(GL.GL_ARRAY_BUFFER, (long) zeros.length * Integer.BYTES, toInt(zeros),
+                GL.GL_DYNAMIC_DRAW);
+        gl.glEnableVertexAttribArray(2);
+        gl.glVertexAttribIPointer(2, 1, GL3.GL_INT, 0, 0L);
+        gl.glBindVertexArray(0);
+    }
+
+    private void bindFloat(GL3 gl, int vbo, float[] data, int loc, int comp) {
+        gl.glBindBuffer(GL.GL_ARRAY_BUFFER, vbo);
+        gl.glBufferData(GL.GL_ARRAY_BUFFER, (long) data.length * Float.BYTES, toFloat(data),
+                GL.GL_DYNAMIC_DRAW);
+        gl.glEnableVertexAttribArray(loc);
+        gl.glVertexAttribPointer(loc, comp, GL.GL_FLOAT, false, 0, 0L);
+    }
+
+    public void draw(GL3 gl, float pointSize) {
+        if (!created) {
+            return;
+        }
+        if (lineVertexCount > 0) {
+            gl.glBindVertexArray(lineVao);
+            gl.glDrawArrays(GL.GL_LINES, 0, lineVertexCount);
+        }
+        if (pointCount > 0) {
+            gl.glPointSize(pointSize);
+            gl.glBindVertexArray(pointVao);
+            gl.glDrawArrays(GL.GL_POINTS, 0, pointCount);
+        }
+        gl.glBindVertexArray(0);
+    }
+
+    public void clear() {
+        pointCount = 0;
+        lineVertexCount = 0;
+    }
+
+    private static FloatBuffer toFloat(float[] d) {
+        FloatBuffer fb = ByteBuffer.allocateDirect(Math.max(1, d.length) * Float.BYTES)
+                .order(ByteOrder.nativeOrder()).asFloatBuffer();
+        fb.put(d).flip();
+        return fb;
+    }
+
+    private static IntBuffer toInt(int[] d) {
+        IntBuffer ib = ByteBuffer.allocateDirect(Math.max(1, d.length) * Integer.BYTES)
+                .order(ByteOrder.nativeOrder()).asIntBuffer();
+        ib.put(d).flip();
+        return ib;
+    }
+}
+```
+
+- [ ] **Step 2: Build to confirm it compiles**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DskipTests compile`
+Expected: BUILD SUCCESS.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/HighlightOverlay.java
+git commit -m "Add HighlightOverlay dynamic marker buffers"
+```
+
+---
+
+### Task 16: `GLViewport` (canvas, render loop, input, picking, screenshot)
+
+The integration hub: creates the `GLCanvas`, wires init/render/reshape/dispose, owns `GlScene`,
+`PickingFramebuffer`, `HighlightOverlay`, `OrbitCamera`, and both shader programs. Handles mouse
+orbit/pan/zoom, exposes `setScene`, `setIndexSet`, `setSelectedId`, `requestPick`, wireframe/cull flags, and
+`screenshot`. All GL work runs inside the render callback; public mutators set fields the callback reads.
+
+**Files:**
+- Create: `.../gui/gl/GLViewport.java`
+
+- [ ] **Step 1: Implement**
+
+```java
+package de.hft.stuttgart.citydoctor2.gui.gl;
+
+import com.huskerdev.grapl.gl.GLProfile;
+import com.huskerdev.openglfx.canvas.GLCanvas;
+import com.huskerdev.openglfx.jogl.JOGLExecutor;
+import com.huskerdev.openglfx.jogl.events.JOGLRenderEvent;
+import com.jogamp.opengl.GL;
+import com.jogamp.opengl.GL3;
+import java.util.concurrent.ConcurrentLinkedQueue;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Consumer;
+import javafx.application.Platform;
+import javafx.scene.input.MouseButton;
+import javafx.scene.paint.Color;
+
+/** OpenGL viewport embedded in JavaFX via openglfx. Replaces the legacy SubScene. */
+public class GLViewport {
+
+    private static final Color BACKGROUND = Color.AZURE;
+
+    private final GLCanvas canvas;
+    private final OrbitCamera camera = new OrbitCamera();
+    private final GlScene scene = new GlScene();
+    private final PickingFramebuffer picking = new PickingFramebuffer();
+    private final HighlightOverlay overlay = new HighlightOverlay();
+
+    private ShaderProgram sceneProgram;
+    private ShaderProgram pickProgram;
+    private boolean initialized;
+
+    // state set off-thread, consumed in render callback
+    private final AtomicReference<SceneData> pendingScene = new AtomicReference<>();
+    private final AtomicReference<int[]> pendingIndexSet = new AtomicReference<>();
+    private final ConcurrentLinkedQueue<float[]> pendingPoints = new ConcurrentLinkedQueue<>();
+    private volatile int selectedId = 0;
+    private volatile boolean wireframe = false;
+    private volatile boolean cull = false;
+    private volatile float pointScale = 5f;
+
+    // pick request: screen coords + callback (invoked on FX thread with resolved Object or null)
+    private volatile int[] pickRequest;     // {x, y} or null
+    private volatile Consumer<Object> pickCallback;
+    private SceneData currentScene;
+
+    // drag state
+    private double lastX;
+    private double lastY;
+
+    public GLViewport() {
+        canvas = new GLCanvas(new JOGLExecutor(), GLProfile.CORE);
+        canvas.addOnInitEvent(ev -> initialized = false); // (re)create resources lazily in render
+        canvas.addOnRenderEvent(ev -> render((JOGLRenderEvent) ev));
+        canvas.addOnReshapeEvent(ev -> { /* aspect handled per-frame from width/height */ });
+        installInputHandlers();
+    }
+
+    public GLCanvas getNode() { return canvas; }
+
+    // ---- public API (called from FX / worker threads) ----
+
+    public void setScene(SceneData data) { pendingScene.set(data); canvas.repaint(); }
+
+    public void setIndexSet(int[] indices) { pendingIndexSet.set(indices); canvas.repaint(); }
+
+    public void setSelectedId(int id) { selectedId = id; canvas.repaint(); }
+
+    public void setWireframe(boolean on) { wireframe = on; canvas.repaint(); }
+
+    public void setCulling(boolean on) { cull = on; canvas.repaint(); }
+
+    public void setPointScale(float scale) { pointScale = scale; canvas.repaint(); }
+
+    /** points: xyz, pointColors rgb-per-point; lines: xyz pairs, lineColors rgb-per-line-vertex. */
+    public void setHighlights(float[] points, float[] pointColors, float[] lines, float[] lineColors) {
+        pendingPoints.add(new float[0]); // wake flag; actual data passed via fields below
+        this.hlPoints = points;
+        this.hlPointColors = pointColors;
+        this.hlLines = lines;
+        this.hlLineColors = lineColors;
+        this.highlightsDirty = true;
+        canvas.repaint();
+    }
+
+    private volatile float[] hlPoints = new float[0];
+    private volatile float[] hlPointColors = new float[0];
+    private volatile float[] hlLines = new float[0];
+    private volatile float[] hlLineColors = new float[0];
+    private volatile boolean highlightsDirty = false;
+
+    public OrbitCamera camera() { return camera; }
+
+    public void requestPick(double x, double y, Consumer<Object> callback) {
+        pickRequest = new int[]{(int) Math.round(x), (int) Math.round(y)};
+        pickCallback = callback;
+        canvas.repaint();
+    }
+
+    // ---- render callback (GL thread) ----
+
+    private void render(JOGLRenderEvent ev) {
+        GL3 gl = ev.getGl();
+        int w = ev.width;
+        int h = ev.height;
+        int defaultFbo = ev.fbo;
+
+        if (!initialized) {
+            sceneProgram = new ShaderProgram(gl, "scene.vert", "scene.frag");
+            pickProgram = new ShaderProgram(gl, "pick.vert", "pick.frag");
+            overlay.init(gl);
+            gl.glEnable(GL.GL_DEPTH_TEST);
+            initialized = true;
+        }
+
+        SceneData newScene = pendingScene.getAndSet(null);
+        if (newScene != null) {
+            scene.upload(gl, newScene);
+            currentScene = newScene;
+        }
+        int[] newIndices = pendingIndexSet.getAndSet(null);
+        if (newIndices != null) {
+            scene.setIndexSet(gl, newIndices);
+        }
+        if (highlightsDirty) {
+            overlay.setPoints(gl, hlPoints, hlPointColors);
+            overlay.setLines(gl, hlLines, hlLineColors);
+            highlightsDirty = false;
+        }
+
+        camera.setAspect(h == 0 ? 1f : (float) w / h);
+        float[] mvp = camera.viewProjection();
+
+        // main pass to the openglfx-provided framebuffer
+        gl.glBindFramebuffer(GL.GL_FRAMEBUFFER, defaultFbo);
+        gl.glViewport(0, 0, w, h);
+        gl.glClearColor((float) BACKGROUND.getRed(), (float) BACKGROUND.getGreen(),
+                (float) BACKGROUND.getBlue(), 1f);
+        gl.glClear(GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT);
+        if (cull) {
+            gl.glEnable(GL.GL_CULL_FACE);
+        } else {
+            gl.glDisable(GL.GL_CULL_FACE);
+        }
+        gl.glPolygonMode(GL.GL_FRONT_AND_BACK, wireframe ? GL3.GL_LINE : GL3.GL_FILL);
+
+        sceneProgram.use(gl);
+        gl.glUniformMatrix4fv(sceneProgram.uniform(gl, "uMVP"), 1, false, mvp, 0);
+        gl.glUniform1i(sceneProgram.uniform(gl, "uSelectedId"), selectedId);
+        scene.draw(gl);
+        overlay.draw(gl, pointScale);
+
+        // picking pass on demand
+        int[] req = pickRequest;
+        if (req != null && currentScene != null) {
+            picking.resize(gl, w, h);
+            picking.bind(gl);
+            gl.glClearColor(0, 0, 0, 1);
+            gl.glClear(GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT);
+            gl.glPolygonMode(GL.GL_FRONT_AND_BACK, GL3.GL_FILL);
+            pickProgram.use(gl);
+            gl.glUniformMatrix4fv(pickProgram.uniform(gl, "uMVP"), 1, false, mvp, 0);
+            scene.draw(gl);
+            int id = picking.readId(gl, req[0], req[1]);
+            Object target = currentScene.pickRegistry().resolve(id);
+            int sel = (target != null) ? id : 0;
+            selectedId = sel;
+            Consumer<Object> cb = pickCallback;
+            pickRequest = null;
+            pickCallback = null;
+            gl.glBindFramebuffer(GL.GL_FRAMEBUFFER, defaultFbo);
+            if (cb != null) {
+                Platform.runLater(() -> cb.accept(target));
+            }
+        }
+    }
+
+    // ---- input ----
+
+    private void installInputHandlers() {
+        canvas.setOnMousePressed(e -> { lastX = e.getX(); lastY = e.getY(); });
+        canvas.setOnMouseDragged(e -> {
+            double dx = e.getX() - lastX;
+            double dy = e.getY() - lastY;
+            lastX = e.getX();
+            lastY = e.getY();
+            if (e.getButton() == MouseButton.PRIMARY) {
+                // signs tuned to match legacy drag direction during manual verification (Task 21)
+                camera.orbit(dx / 3.0, dy / 3.0);
+            } else if (e.getButton() == MouseButton.SECONDARY) {
+                double speed = Math.abs(camera.distance()) / 1000.0;
+                camera.pan(-dx * speed, dy * speed);
+            }
+            canvas.repaint();
+        });
+        canvas.setOnScroll(e -> {
+            camera.zoom(e.getDeltaY() < 0 ? 1.05 : 0.95);
+            canvas.repaint();
+        });
+    }
+
+    public void resetCamera() { camera.reset(); canvas.repaint(); }
+}
+```
+
+> Implementation notes:
+> - The `setHighlights` field-plus-flag pattern keeps the marker upload on the GL thread. Keep the four
+>   `hl*` arrays and the `highlightsDirty` flag; the `pendingPoints` queue line is only a wake nudge and may
+>   be removed if `canvas.repaint()` alone reliably triggers a frame.
+> - `glPolygonMode`/`GL_LINE` constants: `GL3.GL_LINE` and `GL3.GL_FILL` (from `com.jogamp.opengl.GL2GL3`)
+>   — confirm the constant's interface during compile and adjust the import if the symbol resolves elsewhere.
+> - If `canvas.repaint()` is not the correct openglfx trigger in 4.1.19, set the canvas to continuous
+>   rendering via the `fps` constructor arg (e.g. `new GLCanvas(new JOGLExecutor(), GLProfile.CORE, false, 0, 60.0)`)
+>   and drop the explicit `repaint()` calls.
+
+- [ ] **Step 2: Build to confirm it compiles**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DskipTests compile`
+Expected: BUILD SUCCESS. Fix any openglfx/JOGL symbol mismatches now (constants, `getGl()` vs field).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/GLViewport.java
+git commit -m "Add GLViewport integrating canvas, camera, picking and overlay"
+```
+
+---
+
+## Phase 3 — Wire into the GUI
+
+### Task 17: Mount `GLViewport` in `MainWindow.setup3dView`
+
+Replace the JavaFX 3D scene with the GL canvas; keep the north-arrow `ImageView` overlay and click gate.
+
+**Files:**
+- Modify: `.../gui/MainWindow.java` (`setup3dView`, `setupMeshViewControls`, `buildCamera`, fields, getters)
+
+- [ ] **Step 1: Replace the 3D scene construction**
+
+In `setup3dView()`, remove the `SubScene geomScene`, `Group root/world/meshGroup`, `PerspectiveCamera`,
+`AmbientLight`, and the `cameraXRotation`/`cameraZRotation` transforms. Construct and mount the viewport:
+
+```java
+private GLViewport glViewport;
+
+private void setup3dView() {
+    glViewport = new GLViewport();
+    GLCanvas canvas = glViewport.getNode();
+    canvas.prefWidthProperty().bind(meshView.widthProperty());
+    canvas.prefHeightProperty().bind(meshView.heightProperty());
+    meshView.getChildren().add(canvas);
+
+    // click-to-pick gate (replaces JavaFX pickResult)
+    canvas.addEventFilter(MouseEvent.MOUSE_PRESSED, me -> {
+        clickStart[0] = me.getScreenX();
+        clickStart[1] = me.getScreenY();
+    });
+    canvas.addEventFilter(MouseEvent.MOUSE_RELEASED, me -> {
+        if (Math.abs(clickStart[0] - me.getScreenX()) > 3 || Math.abs(clickStart[1] - me.getScreenY()) > 3) {
+            return; // treated as a drag, not a click
+        }
+        double x = me.getX();
+        double y = me.getY();
+        glViewport.requestPick(x, y, target -> {
+            if (target instanceof ClickDispatcher cd) {
+                cd.click(me, clickHandler);
+            }
+        });
+    });
+
+    // north arrow overlay stays on top
+    north = new Image(getClass().getResourceAsStream("icons/north.png"), 50, 50, true, true);
+    northFlip = new Image(getClass().getResourceAsStream("icons/north_flip.png"), 50, 50, true, true);
+    northArrow = new ImageView(north);
+    northArrow.setFitHeight(50);
+    northArrow.setFitWidth(50);
+    northArrow.setX(10);
+    northArrow.setY(10);
+    meshView.getChildren().add(northArrow);
+    northArrow.setVisible(false);
+}
+```
+
+> `ClickDispatcher`/`PolygonClickDispatcher`/`VertexClickDispatcher` currently carry the clicked model
+> object. Picking now resolves a `Polygon`/`Vertex`/`Edge` directly. Bridge it: in the pick callback, map
+> the resolved object to the existing dispatch. Simplest: have `PolygonClickDispatcher`/`VertexClickDispatcher`
+> remain the things stored in the `PickRegistry` instead of raw `Polygon`/`Vertex`. To do that, change
+> `SceneBuilder` to `registry.register(new PolygonClickDispatcher(p))` and resolve to `ClickDispatcher`.
+> Update Task 10's `instanceof Polygon` test expectation to `instanceof PolygonClickDispatcher` if you take
+> this route. Pick whichever keeps `ClickDispatcher.click(...)` working and keep it consistent.
+
+- [ ] **Step 2: Update camera input + zoom plumbing**
+
+`setupMeshViewControls()` mouse/scroll handlers are superseded by `GLViewport.installInputHandlers()`.
+Delete the orbit/pan/scroll bodies that referenced `camera`/`cameraXRotation`. Keep `alignNorthArrow()` and
+call it from a camera-changed hook (simplest: call `alignNorthArrow()` inside the canvas drag handler after
+`glViewport`'s handler runs, using `glViewport.camera()` angles — add accessors `azimuthDeg()/elevationDeg()`
+to `OrbitCamera` if needed for the arrow math).
+
+Update `buildCamera()`, `resetCamera()`, `zoomOutForBoundingBox()`:
+
+```java
+public void resetCamera() {
+    glViewport.resetCamera();
+    alignNorthArrow();
+}
+
+public void zoomOutForBoundingBox(BoundingBox b) {
+    glViewport.camera().zoomOutForBoundingBox(b.getDiagonalLength());
+    glViewport.getNode().repaint();
+    controller.setOriginBB(b);
+}
+```
+
+Delete the now-unused `camera`, `cameraXRotation`, `cameraZRotation`, `translateZ`, `cameraXRot`,
+`cameraYRot` fields and `buildCamera()` if fully replaced (keep `clickStart`).
+
+- [ ] **Step 3: Replace `getMeshGroup()` and `takeViewScreenshot()`**
+
+Remove `getMeshGroup()` (callers updated in Task 18). Replace screenshot to read the GL framebuffer — for
+now, route through the canvas snapshot which openglfx supports as a JavaFX `Region`:
+
+```java
+public void takeViewScreenshot() throws IOException {
+    WritableImage snapshot = glViewport.getNode().snapshot(null, null);
+    File outputFile = new File("img.png");
+    BufferedImage bImage = SwingFXUtils.fromFXImage(snapshot, null);
+    ImageIO.write(bImage, "png", outputFile);
+}
+```
+
+- [ ] **Step 4: Build**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DskipTests compile`
+Expected: compile errors only where `Renderer` still calls `getMeshGroup()` — fixed in Task 18. If you do
+Task 18 in the same session, build at the end of 18 instead.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/MainWindow.java
+git commit -m "Mount GLViewport in MainWindow, route clicks through GPU picking"
+```
+
+---
+
+### Task 18: Rewire `Renderer` to build `SceneData` and drive `GLViewport`
+
+Keep `Renderer`'s public API; replace `TriangulatedGeometry`/`meshGroup` usage with `SceneBuilder` +
+`GLViewport`. Filter/LOD/roof state now produces an index-set predicate.
+
+**Files:**
+- Modify: `.../gui/Renderer.java`
+- Modify: `.../gui/MainWindow.java` (add `getGlViewport()` accessor)
+
+- [ ] **Step 1: Add a viewport accessor to `MainWindow`**
+
+```java
+public GLViewport getGlViewport() { return glViewport; }
+```
+
+- [ ] **Step 2: Replace scene construction in `Renderer`**
+
+Replace fields `currentTriGeom`/`meshGroup` usage. Keep the existing filter objects (`lodFilters`,
+`roofFilter`). After building `SceneData`, build the initial index set from the active filters and push both
+to the viewport. Core changes:
+
+```java
+private SceneData currentScene;
+
+private void setupRenderState() {
+    GLViewport vp = mainWindow.getGlViewport();
+    vp.setScene(currentScene);
+    rebuildIndexSet();
+    vp.setCulling(currentCulling == CullFace.BACK);
+    vp.setWireframe(currentDrawMode == DrawMode.LINE);
+    mainWindow.getGridButton().setDisable(false);
+    mainWindow.getCullingButton().setDisable(false);
+}
+
+private void rebuildIndexSet() {
+    if (currentScene == null) {
+        return;
+    }
+    int[] indices = IndexSetBuilder.build(currentScene.triangleMetas(), this::triangleVisible);
+    mainWindow.getGlViewport().setIndexSet(indices);
+}
+
+private boolean triangleVisible(TriangleMeta m) {
+    // LOD filter: at least one enabled lodFilter must accept this triangle's lod
+    boolean lodOk = false;
+    for (ViewFilter f : lodFilters) {
+        if (f.isEnabled() && f.acceptsLod(m.lod())) { // add acceptsLod helper or compare ordinals
+            lodOk = true;
+            break;
+        }
+    }
+    if (!lodOk) {
+        return false;
+    }
+    // roof filter
+    return !(roofFilter.isEnabled() && m.roof());
+}
+```
+
+> The legacy `ViewFilter` decides on `(CityObject, Geometry)`. Here triangles already carry `lod`/`roof`.
+> Add small helpers to `TriangleMeta`/filters as needed, or store the `Lod` ordinal on `TriangleMeta`
+> (already present) and compare against each filter's target LOD. Keep the visible-set semantics identical
+> to the legacy `addPolygons`/`isGeometryFiltered` logic (a triangle shows iff its LOD filter is enabled and,
+> when roof-hiding is on, it is not a roof).
+
+Replace the various `render(...)` methods so they:
+1. build `SceneData` via `SceneBuilder` (using the same per-feature base colors as the legacy
+   `TriangulatedGeometry.of(model, filters)` — port that feature/color iteration into a
+   `SceneBuilder.fromModel(model)` overload that tags each triangle's `lod`/`roof`),
+2. assign `currentScene`,
+3. call `setupRenderState()` on the FX thread.
+
+The LOD enable/disable and roof methods call `rebuildIndexSet()` instead of `refresher.run()` when only the
+filter changed:
+
+```java
+public void enableLod1() { lodFilters.get(0).enable(); rebuildIndexSet(); }
+// ...same pattern for the other LOD toggles and hideRoofs/showRoofs...
+```
+
+- [ ] **Step 3: Replace highlight/wireframe/cull delegations**
+
+```java
+public void showWireFrame(boolean show) {
+    currentDrawMode = show ? DrawMode.LINE : DrawMode.FILL;
+    mainWindow.getGlViewport().setWireframe(show);
+}
+
+public void enableCulling(boolean enable) {
+    currentCulling = enable ? CullFace.BACK : CullFace.NONE;
+    mainWindow.getGlViewport().setCulling(enable);
+}
+```
+
+Highlight methods delegate to `HighlightController` (rewritten in Task 19), which pushes marker arrays to
+the viewport. Selection of a clicked polygon: when a pick resolves, set the selected id via
+`vp.setSelectedId(id)` (the `GLViewport` already does this in its pick handler; `Renderer.highlight(Polygon)`
+should additionally drive the overlay markers through `HighlightController`).
+
+- [ ] **Step 4: Build**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DskipTests compile`
+Expected: BUILD SUCCESS once `HighlightController` (Task 19) compiles. If splitting sessions, stub the
+highlight calls to no-ops to get a green compile, then implement Task 19.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/Renderer.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/MainWindow.java
+git commit -m "Drive GLViewport from Renderer via SceneBuilder and index sets"
+```
+
+---
+
+### Task 19: Rewrite `HighlightController` to feed the overlay
+
+Replace JavaFX `Sphere`/`Cylinder` node creation with arrays of marker points/lines pushed to
+`GLViewport.setHighlights`. Keep the public method names so callers (`Renderer`, error visitors) are
+unchanged. Positions are recentred using the current scene center.
+
+**Files:**
+- Modify: `.../gui/HighlightController.java`
+
+- [ ] **Step 1: Replace internals**
+
+Constructor takes the `GLViewport` (and the current scene center supplier). Maintain growing point/line
+lists; on each `highlight*`/`clearHighlights`, rebuild and call `setHighlights`. Marker color → rgb floats.
+`changeScaling(translateZ)` maps to `GLViewport.setPointScale(...)` using the same clamp math as today
+(`scale = clamp(|z|,10,150) * 0.01`, then point size in pixels, e.g. `scale * BASE_POINT_PX`).
+
+```java
+public class HighlightController {
+
+    private final GLViewport viewport;
+    private java.util.function.Supplier<double[]> centerSupplier; // current scene center
+    private final FloatList points = new FloatList();
+    private final FloatList pointColors = new FloatList();
+    private final FloatList lines = new FloatList();
+    private final FloatList lineColors = new FloatList();
+    private float pointScale = 5f;
+
+    public HighlightController(GLViewport viewport) {
+        this.viewport = viewport;
+    }
+
+    public void setCenterSupplier(java.util.function.Supplier<double[]> supplier) {
+        this.centerSupplier = supplier;
+    }
+
+    public void clearHighlights() {
+        // reset lists
+        // (FloatList currently has no clear(); add a clear() that resets size to 0)
+        flush(true);
+    }
+
+    public void changeScaling(double translateZ) {
+        double s = Math.min(150, Math.max(10, Math.abs(translateZ))) * 0.01;
+        pointScale = (float) (s * 8.0); // BASE_POINT_PX tuned in verification
+        viewport.setPointScale(pointScale);
+    }
+    // highlight(Polygon), highlight(LinearRing), highlight(Edge), highlight(Vertex),
+    // highlight(List<LinearRing>), highlightEdges, highlightPolygons, addHighlight(...) :
+    //   compute recentred xyz for each vertex -> points + color; for each edge -> 2 line endpoints.
+    //   Then call flush(false).
+}
+```
+
+Add `FloatList.clear()` (set `size = 0`) — update `FloatListTest` with a `clear()` case in the same commit.
+
+`flush(boolean cleared)` calls
+`viewport.setHighlights(points.toArray(), pointColors.toArray(), lines.toArray(), lineColors.toArray());`
+
+Port the per-vertex recentring from the old `highlightPoint`/`highlightEdge` (subtract scene center). The
+sphere→point and cylinder→line mapping preserves which vertices/edges are shown and their colors (RED/BLUE
+exterior/interior, ORANGE edges, the multi-color `highlightPolygons` palette).
+
+- [ ] **Step 2: Update construction site**
+
+In `MainWindow.start(...)`, `HighlightController` is built with `world` today
+(`new HighlightController(world)`). Change to `new HighlightController(glViewport)` and wire the center
+supplier from the `Renderer`'s current `SceneData` (`() -> currentScene == null ? new double[3] : currentScene.center()`).
+
+- [ ] **Step 3: Build**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DskipTests compile`
+Expected: BUILD SUCCESS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/HighlightController.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/MainWindow.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/gl/FloatList.java \
+        CityDoctorParent/Extensions/CityDoctorGUI/src/test/java/de/hft/stuttgart/citydoctor2/gui/gl/FloatListTest.java
+git commit -m "Render highlights through GL overlay instead of JavaFX nodes"
+```
+
+---
+
+### Task 20: Delete `TriangulatedGeometry` and dead JavaFX 3D code
+
+**Files:**
+- Delete: `.../gui/TriangulatedGeometry.java`
+- Modify: any remaining references (`ListErrorVisitor`, `GlobalErrorVisitor`, `Renderer`)
+
+- [ ] **Step 1: Find references**
+
+Run: `grep -rn "TriangulatedGeometry\|getMeshGroup\|setDrawMode\|setCullFace" CityDoctorParent/Extensions/CityDoctorGUI/src/main`
+Expected: a short list. `ListErrorVisitor.setGeometry(TriangulatedGeometry)` likely needs to take
+`SceneData`/`GLViewport` instead, or be reworked to call `Renderer.highlight(...)` paths. Update each to the
+new highlight API (the visitors ultimately call `highlightController`/`renderer.highlight(...)`).
+
+- [ ] **Step 2: Delete the class and fix references**
+
+```bash
+git rm CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/TriangulatedGeometry.java
+```
+Then update the references found in Step 1 so they compile against the new API.
+
+- [ ] **Step 3: Build + run the full module test suite**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DfailIfNoTests=false test`
+Expected: BUILD SUCCESS; the Phase 1 unit tests pass. (Per project norms, ignore unrelated known-failing
+charset/GUI tests noted in repo memory.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add -A
+git commit -m "Remove TriangulatedGeometry and dead JavaFX 3D rendering code"
+```
+
+---
+
+## Phase 4 — Manual verification & packaging
+
+### Task 21: Run the app and verify feature parity
+
+**Files:** none (verification only; fixes go back into the relevant task's files)
+
+- [ ] **Step 1: Launch with a sample model**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -DskipTests exec:java -Dexec.mainClass=de.hft.stuttgart.citydoctor2.gui.MainWindow`
+Then open `CityDoctorParent/Extensions/CityDoctorGUI/src/test/resources/SimpleSolid_SrefBS-GE-gml-LR-0001-T0001.gml`
+(or a larger city model).
+
+- [ ] **Step 2: Verify each feature and note pass/fail**
+
+Check, and fix the owning class where a check fails:
+- Geometry renders with surface-differentiating shades (ShadeColor). 
+- Orbit (left-drag), pan (right-drag), zoom (scroll) behave like before; if drag direction is inverted,
+  flip the delta signs in `GLViewport.installInputHandlers` (Task 16).
+- Reset camera, north arrow alignment.
+- Click a polygon → it highlights (selection tint) and the tree/error panels respond (picking + dispatch).
+- Vertex/edge highlights appear at the right places and scale with zoom.
+- LOD1–4 toggles, hide-roofs toggle change what's drawn.
+- Wireframe toggle, back-face culling toggle.
+- Per-polygon error coloring after a validation run.
+- Screenshot button writes `img.png`.
+
+- [ ] **Step 3: Verify performance on a large model**
+
+Load a multi-building/city model; confirm orbit/zoom stays smooth (no multi-second stalls as before).
+If picking causes a hitch, confirm readback only happens on click (it does, by design).
+
+- [ ] **Step 4: Commit any fixes**
+
+```bash
+git add -A
+git commit -m "Fix OpenGL view issues found during manual verification"
+```
+
+---
+
+### Task 22: Packaging — ship JOGL/openglfx natives in win/linux bundles
+
+**Files:**
+- Modify: `CityDoctorParent/Extensions/CityDoctorGUI/src/assembly/win/assembly.xml`
+- Modify: `CityDoctorParent/Extensions/CityDoctorGUI/src/assembly/lin/assembly.xml`
+- (Inspect, likely no change) `.../src/assembly/no_runtime/assembly.xml`
+
+- [ ] **Step 1: Inspect the assembly descriptors**
+
+Run: `ls CityDoctorParent/Extensions/CityDoctorGUI/src/assembly && cat CityDoctorParent/Extensions/CityDoctorGUI/src/assembly/win/assembly.xml`
+Confirm how dependency jars are bundled (a `dependencySets` block). The openglfx + JOGL native jars
+(`*-natives-windows-amd64.jar`, `*-natives-linux-amd64.jar`, `grapl-natives-*`, `openglfx-natives-*`) must be
+included on the runtime classpath. If `dependencySets` already includes all runtime-scope deps, no change is
+needed — verify the native jars appear.
+
+- [ ] **Step 2: Build the Windows/Linux bundles**
+
+Run: `mvn -pl Extensions/CityDoctorGUI -am -Pcreate-binaries install`
+Expected: bundles produced under `target/`. Inspect that native jars are present in the assembled lib dir.
+
+- [ ] **Step 3: Smoke-launch a bundle**
+
+Unzip the produced `-win`/`-lin` (as applicable to your OS) bundle and launch its start script; confirm the
+3D view renders (no `UnsatisfiedLinkError`).
+
+- [ ] **Step 4: Commit any descriptor changes**
+
+```bash
+git add CityDoctorParent/Extensions/CityDoctorGUI/src/assembly/
+git commit -m "Bundle JOGL/openglfx natives in win/linux distributions"
+```
+
+---
+
+### Task 23: Changelog & docs
+
+**Files:**
+- Modify: `CHANGELOG.md`
+
+- [ ] **Step 1: Add a changelog entry**
+
+Add under the current unreleased section:
+
+```markdown
+- Replaced the JavaFX-based 3D view with an OpenGL renderer (openglfx/JOGL) for smooth display of
+  large city models. Picking is now GPU-based; the 3D view requires OpenGL 3.3 (Windows/Linux).
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add CHANGELOG.md
+git commit -m "Document OpenGL 3D view in changelog"
+```
+
+---
+
+## Self-Review notes (for the executor)
+
+- **Spec coverage:** §3 components → Tasks 11–19; single global VBO + index set → Tasks 7,8,13,18; picking
+  → Tasks 2,3,14,16,17; baked fake shading → Tasks 4,10,12; selection tint → Tasks 12,16; overlay highlights
+  → Tasks 15,19; feature parity → Task 21; removals → Task 20; packaging → Task 22.
+- **Consistency to watch:** `PickingCodec` byte order (red = low byte) must match `pick.frag`. The
+  `PickRegistry` stores either raw `Polygon`/`Vertex`/`Edge` or `ClickDispatcher` wrappers — pick one in
+  Task 10/17 and keep `SceneBuilderTest`'s `instanceof` assertion aligned. `FloatList.clear()` is introduced
+  in Task 19; update its test in the same commit.
+- **Known soft spots needing run-time tuning (called out inline):** camera handedness/drag-sign
+  (Task 6/16/21), openglfx repaint vs continuous-render trigger (Task 16), `glPolygonMode` constant
+  interface (Task 16), screenshot via `Region.snapshot` vs `glReadPixels` (Task 17 — upgrade to framebuffer
+  readback if the snapshot of a GL canvas comes back blank).

docs/superpowers/specs/2026-06-18-opengl-3d-view-design.md

+# OpenGL 3D View — Design Spec
+
+**Date:** 2026-06-18
+**Branch:** 107-opengl-view
+**Component:** `CityDoctorParent/Extensions/CityDoctorGUI`
+
+## 1. Problem & Goal
+
+The GUI renders 3D CityGML geometry with JavaFX, tesselating **each polygon into its own
+`TriangleMesh` + `MeshView` + `PhongMaterial`** (see `TriangulatedGeometry`). At city scale this
+produces thousands of scene-graph nodes, each with its own material — the JavaFX node overhead, not
+just the lack of shader access, makes orbit/zoom stutter or freeze.
+
+**Goal:** Replace the JavaFX `SubScene` 3D view with an OpenGL-rendered viewport that orbits, zooms,
+and pans smoothly on whole-city models (millions of triangles), while preserving every existing view
+feature (picking, highlights, filters, wireframe, culling, north arrow, screenshot).
+
+## 2. Decisions (settled during brainstorming)
+
+| Topic | Decision |
+|-------|----------|
+| Scale target | Whole cities, millions of triangles; smooth (30–60 fps) interaction. |
+| Integration | Embed an OpenGL canvas via the already-present `openglfx-jogl` (huskerdev) dependency, in the `meshView` `Pane` where the `SubScene` lives today. |
+| GL version | OpenGL **3.3 core profile**, GLSL shaders, VAO/VBO. |
+| Platforms | **Windows + Linux** are hard targets. macOS bundle still builds but the GL view may degrade — accepted. |
+| JavaFX 3D path | **Fully removed** (no fallback). |
+| Buffer strategy | **Single global static VBO**; one `glDrawElements` per frame; filter/LOD changes rebuild the draw **index set** (EBO), not the VBO. |
+| Picking | **GPU color-picking**: off-screen FBO encodes `polygonId` per fragment; `glReadPixels` on click. |
+| Shading | **Keep existing fake shading** (`normal·AXIS` → brightness), **baked into per-vertex color on the CPU** at build time. No lighting in the shader. Normal attribute dropped from the VBO. |
+| Selection | Shader `selectedId` uniform tints matching fragments — no buffer mutation. |
+| Vertex/edge highlights | Separate small **dynamic** GL overlay buffer (replaces JavaFX `Sphere`/`Cylinder`). |
+
+## 3. Architecture & Components
+
+New/changed classes in `de.hft.stuttgart.citydoctor2.gui` (or a new `gui.gl` sub-package):
+
+- **`GLViewport`** *(new)* — wraps the openglfx canvas, owns the GL context, the render callback, the
+  `Camera`, and GL resources (shaders, VAO/VBO/EBO, picking FBO, overlay buffer). Replaces the JavaFX
+  `SubScene`/`world`/`meshGroup`/`PerspectiveCamera`/`AmbientLight` built in `MainWindow.setup3dView`.
+- **`SceneBuilder`** *(replaces `TriangulatedGeometry`)* — flattens the model into interleaved vertex
+  data and the `id → Polygon/Vertex/Edge` maps. Runs on a worker thread (as `Renderer.render` already
+  does). Reuses existing `Polygon.tesselate()` → `TesselatedPolygon`/`Triangle3d`, the
+  `findCenter`/`movedBy` recentering, and the `calculateMaterial` shade math.
+- **`SceneBuffers`** *(new)* — owns the global VBO + static vertex data and rebuilds/uploads the draw
+  index set on filter/LOD changes. GL-thread owned; uploads queued from the worker thread.
+- **`Camera`** *(new)* — view/projection matrices replicating today's interaction: orbit (Z + X
+  rotation, today on the `world` group), right-drag pan, scroll zoom, `zoomOutForBoundingBox`,
+  `resetCamera`. Reuses the existing angle/translate state in `MainWindow`.
+- **`PickingPass`** *(new)* — off-screen FBO sized to the canvas; renders the `polygonId` pass and
+  reads back the cursor pixel on click.
+- **`HighlightOverlay`** *(replaces the `Sphere`/`Cylinder` rendering in `HighlightController`)* —
+  small dynamic buffer for vertex/edge markers, rescaled on zoom like `changeScaling` does now.
+- **`Renderer`** *(kept)* — **public API unchanged** (`render(model)`, `render(Geometry)`,
+  `render(CityObject)`, `highlight(...)`, `showWireFrame`, `enableCulling`, `enableLodN`/`disableLodN`,
+  `hideRoofs`/`showRoofs`, `clearCurrentRender`, etc.) so `CityDoctorController`, `MainWindow`, and the
+  error visitors (`ListErrorVisitor`, `GlobalErrorVisitor`) are largely untouched. Internally it drives
+  `SceneBuilder`/`SceneBuffers`/`GLViewport` instead of the JavaFX `meshGroup`.
+
+## 4. Geometry Pipeline (single global VBO)
+
+At load, off the FX thread:
+
+1. Iterate city objects → polygons → `tesselate()` → triangles, recentered by `movedBy`
+   (`SceneBuilder.findCenter`, same as today).
+2. Build **one interleaved static VBO** with per-vertex attributes:
+   - `position` — `vec3 float`
+   - `color` — `vec3 float`, the **baked shaded color** (see §6)
+   - `polygonId` — `uint` (or packed into a `vec4` for the picking pass)
+   (No normal attribute — shading is baked, picking/selection use the id.)
+3. Build CPU-side maps **`polygonId → Polygon`** (and ids for vertices/edges) — these replace the
+   per-`MeshView` `userData` dispatchers (`PolygonClickDispatcher`, `VertexClickDispatcher`).
+4. Build an **index buffer (EBO)** listing the triangles to draw. The existing `Renderer` filter set
+   (`lodFilters`, `roofFilter`) determines membership; toggling a filter rebuilds the index array on
+   the CPU and re-uploads it. The VBO is never touched. One `glDrawElements` per frame.
+
+`polygonId` is a 32-bit value (RGBA8 in the picking FBO → ~4.2B ids), more than enough.
+
+## 5. Render Loop & Threading
+
+- openglfx calls a render callback on its GL render thread with a live context. The callback only
+  **draws** from prepared buffers (main pass; picking pass on demand; overlay pass).
+- GL resource **creation/upload** also happens on the GL thread: `SceneBuilder` runs on a worker
+  thread and **queues** the prepared arrays; the render callback drains the queue and uploads.
+- FX-thread code (filter toggles, tree selection, camera input) sets dirty flags / state the render
+  callback consumes. No GL calls off the GL thread.
+
+## 6. Shading (baked, fake)
+
+Keep the current surface-differentiation shading. At build time, for each polygon compute exactly as
+`TriangulatedGeometry.calculateMaterial` does today:
+
+```
+normal = p.calculateNormalNormalized()
+base   = p.getRenderColor() (if set and not WHITE) else feature base color
+acos   = Math.acos(normal·AXIS) / Math.PI        // AXIS = normalize(19, 0.8, 1.5)
+shade  = acos * 0.6 + 0.3                          // range [0.3, 0.9]
+vertexColor = base.deriveColor(0, 1.0, shade, 1.0)
+```
+
+Store `vertexColor` as the per-vertex `color` attribute. The fragment shader outputs the interpolated
+vertex color directly — no lighting computation in the shader.
+
+## 7. Picking (GPU color-picking)
+
+- A picking shader writes `polygonId` (as RGBA8) into an off-screen FBO sized to the canvas.
+- On click, reuse `MainWindow`'s existing press/release "did the mouse move >3px?" gate. Render (or
+  reuse) the id pass, `glReadPixels` the cursor pixel → `polygonId` → `Polygon`/`Vertex`/`Edge` via the
+  CPU map → same downstream handling that `PolygonClickDispatcher`/`VertexClickDispatcher` perform now.
+- Readback only on click (never per frame) to avoid GPU stalls.
+
+## 8. Selection & Highlights
+
+- **Selection tint:** the main shader takes a `selectedId` uniform (or a small id set); fragments whose
+  id matches are tinted. Highlighting a clicked polygon needs no buffer mutation.
+- **Vertex/edge markers** (today's `HighlightController` spheres/cylinders): drawn from a separate
+  **dynamic** buffer after the main pass — points/instanced quads for vertices, line segments (or thin
+  instanced cylinders) for edges — rescaled on zoom as `changeScaling` does today. `HighlightController`
+  keeps its public API (`highlight(Polygon/LinearRing/Edge/Vertex/...)`, `clearHighlights`,
+  `changeScaling`, `highlightEdges`, `highlightPolygons`) so callers are unaffected.
+
+## 9. Feature Parity Checklist
+
+All preserved:
+- LOD1–LOD4 filters, hide-roofs toggle (index-set rebuild).
+- Wireframe (`DrawMode.LINE` → `glPolygonMode(GL_LINE)` with the black grid color).
+- Back-face culling toggle (`glEnable/Disable(GL_CULL_FACE)`).
+- Per-feature base colors and per-polygon error coloring (`Polygon.getRenderColor()`).
+- Vertex/edge/polygon highlighting.
+- North-arrow overlay — stays a JavaFX `ImageView` layered on top of the GL canvas in the `meshView`
+  `Pane`; `alignNorthArrow` logic unchanged.
+- Screenshot (`MainWindow.takeViewScreenshot`) — `glReadPixels` of the framebuffer → `BufferedImage` →
+  PNG, replacing `SubScene.snapshot`.
+- Camera orbit/pan/zoom, `resetCamera`, `zoomOutForBoundingBox`.
+
+## 10. Removals
+
+- `TriangulatedGeometry` (replaced by `SceneBuilder`/`SceneBuffers`).
+- The JavaFX 3D scene in `MainWindow.setup3dView`: `SubScene geomScene`, `world`/`meshGroup` groups,
+  `PerspectiveCamera`, `AmbientLight`, `cameraXRotation`/`cameraZRotation` transforms, and
+  `getMeshGroup()`.
+- `Sphere`/`Cylinder` rendering inside `HighlightController` (logic moves to `HighlightOverlay`).
+- Mesh-level JavaFX picking (`pickResult.getIntersectedNode()` → replaced by color-picking).
+
+## 11. Risks & Mitigations
+
+- **Native lib packaging:** openglfx + JOGL natives must ship in the win/lin assembly descriptors
+  (`src/assembly/{win,lin}/assembly.xml`). Verify the assembled bundles launch and render.
+- **GL context lifecycle vs JavaFX resize:** handle canvas resize (recreate picking FBO, update
+  viewport/projection).
+- **Picking readback stalls:** mitigated by reading only on click.
+- **macOS degradation:** accepted; not a hard target.
+
+## 12. Testing
+
+- **Unit (headless):** `SceneBuilder` flattening — vertex/triangle counts, `id → Polygon` mapping
+  correctness, recentering by `movedBy`, baked-color math matches `calculateMaterial`.
+- **Manual/visual:** rendering correctness, picking accuracy (click → correct polygon/vertex/edge),
+  filter/LOD/roof toggles, wireframe, culling, highlights, north arrow, screenshot, camera controls —
+  on a large city model, confirming smooth interaction.
+
+## 13. Out of Scope
+
+- LOD-of-detail mesh simplification / frustum culling / occlusion culling (single global VBO + one draw
+  call is expected to suffice; revisit only if profiling shows a need).
+- macOS-specific GL/threading work.
+- Any change to validation, parsing, or non-GUI modules.