Explicit Coordinates: Which Option Should I Use?

Page Info

• Audience: Beginner to Intermediate

• Prerequisites: MTG Reconstruction Tutorial, AMAP Conventions Reference

• Time: 8 minutes

• Output: Clear choice of explicit-coordinate option in AmapReconstructionOptions

This page is a focused follow-up to the tutorial and the reference page.

By the time you read it, you should already know:

• whether your MTG contains XX, YY, ZZ

• whether it also contains EndX, EndY, EndZ

• that these columns describe explicit node coordinates rather than topology-derived placement

This page is about one specific reconstruction option:

AmapReconstructionOptions(explicit_coordinate_mode=...)

You pass this option to reconstruction like this:

set_geometry_from_attributes!(
    mtg,
    prototypes;
    convention=default_amap_geometry_convention(),
    amap_options=AmapReconstructionOptions(explicit_coordinate_mode=:topology_default),
)

Use this page only if your MTG contains explicit coordinates such as XX, YY, ZZ, EndX, EndY, EndZ.

If your MTG only contains sizes and angles (Length, Width, YInsertionAngle, XEuler, ...), you do not need this page yet. Stay with the default reconstruction from MTG Reconstruction Tutorial.

If instead you need the full list of accepted MTG columns or aliases, go back to AMAP Conventions Reference.

What This Page Assumes

This page does not re-list all AMAP variables. It assumes you already know the coordinate columns:

Column family	Meaning
XX, YY, ZZ	explicit start position of the node
EndX, EndY, EndZ	explicit end position of the node
Offset, insertion angles, Euler angles	topology-driven fallback when explicit coordinates do not fully define the node

So the only question left is:

when explicit coordinates are present, how should PlantGeom combine them with the topology-driven reconstruction?

What This Option Controls

explicit_coordinate_mode tells PlantGeom what to do when node coordinates are present in the MTG.

Without explicit coordinates:

• node positions are reconstructed from topology (:<, :+, :/) and attributes such as Offset, insertion angles, and Euler angles.

With explicit coordinates:

• PlantGeom must decide whether these coordinates:

  • simply place the current node,

  • rewire the previous segment,

  • or require a full start/end segment definition.

That is exactly what explicit_coordinate_mode chooses.

In other words:

• the reference page tells you which columns exist

• this page tells you how to choose the controller behavior when those coordinate columns are present

Quick Chooser

Your MTG contains	You want	Use in AmapReconstructionOptions(...)
No XX/YY/ZZ	Standard MTG reconstruction from topology + angles	do nothing; default is fine
XX/YY/ZZ, but no EndX/EndY/EndZ	Coordinates place the node base, but the node stays a visible segment	explicit_coordinate_mode=:topology_default
XX/YY/ZZ, but no EndX/EndY/EndZ	Coordinates should act as control points that bend/rewire the previous segment	explicit_coordinate_mode=:explicit_rewire_previous
XX/YY/ZZ and complete EndX/EndY/EndZ	Each explicit node should be reconstructed from a known start and end	explicit_coordinate_mode=:explicit_start_end_required

The Three Modes in Plain Language

1. :topology_default

Use this when:

• you have some explicit base coordinates,

• but you still want the current node to be a normal visible segment,

• and you still want angles/topology to define direction when end coordinates are missing.

Mental model:

• XX/YY/ZZ says where the node starts

• the rest of the geometry is still reconstructed normally

This is the safest choice for most users.

opts = AmapReconstructionOptions(explicit_coordinate_mode=:topology_default)

2. :explicit_rewire_previous

Use this when:

• your explicit coordinates come from a topology editor or manual control-point workflow,

• and a node position is intended to redirect the previous segment.

Mental model:

• explicit nodes are used as control points

• the previous segment is rewired toward that point

• the current explicit node becomes a point-anchor rather than a normal visible cylinder

This is more specialized. Use it only if you know your data was produced that way.

opts = AmapReconstructionOptions(explicit_coordinate_mode=:explicit_rewire_previous)

3. :explicit_start_end_required

Use this when:

• you trust your explicit coordinates fully,

• and your MTG stores both node start and node end coordinates.

Mental model:

• XX/YY/ZZ gives the start

• EndX/EndY/EndZ gives the end

• PlantGeom builds the segment directly from those two points

If end coordinates are missing, the node geometry is omitted on purpose.

opts = AmapReconstructionOptions(explicit_coordinate_mode=:explicit_start_end_required)

Recommended Starting Point

Start with:

opts = AmapReconstructionOptions(explicit_coordinate_mode=:topology_default)

Then switch only if your data clearly matches one of these cases:

• topology-editor style control points: :explicit_rewire_previous

• complete and trusted start/end coordinates: :explicit_start_end_required

That is the main recommendation for most users:

• if you are unsure, choose :topology_default

• only move away from it when your data source clearly encodes a different intent

Minimal Code Patterns

using PlantGeom

opts = AmapReconstructionOptions(
    explicit_coordinate_mode=:topology_default,
)

set_geometry_from_attributes!(
    mtg,
    prototypes;
    convention=default_amap_geometry_convention(),
    amap_options=opts,
)

opts = AmapReconstructionOptions(
    explicit_coordinate_mode=:explicit_rewire_previous,
)

opts = AmapReconstructionOptions(
    explicit_coordinate_mode=:explicit_start_end_required,
)

Where To Go Next

• If you need the full list of AMAP variables and aliases again: AMAP Conventions Reference

• If you want to keep working from the standard measured-MTG workflow: MTG Reconstruction Tutorial