0041 - A convention the file does not state is declared by the caller; a vertical without a CRS is signalled
Status: accepted
Context
Several readings around a well depend on a fact the files do not say: where an angle around the hole starts and which way it grows, which dimension of a per-node matrix is the slow one and the sign of its lateral axis, which hand a placed frame has. Two readings of the same array give two pictures, and both look plausible; only the producer knows which is right. A library that picks one draws something that looks like data.
Another case is a line read without any coordinate system. The conversion from
depth to z needs to know which way is up. Without a CRS the library has long
taken depth as downward, which is the usual case and also a guess.
Decision
- A convention the file does not state is a parameter, declared by the
caller (
AngleConvention: origin, sense, side from which it is seen, offset;TransverseGrid: the axis, the sign and the offsets of each dimension; the handedness of a frame inFrameOptions). Until it is declared, the layer that needs it is refused by name (ConventionUndeclared). There is no default and no “unknown” state: the caller choosesRegularor states a convention. It is registered ashouse/well/conventions-are-declared. - A declaration is never written into the package by these functions, and it never overrides what the file states (ADR 0032). Writing one is the business of an operation that edits a working copy, not of a reading.
- The canonical plane is fixed: as seen by an observer standing uphole and
looking down the hole,
rightto the right andhigh_sideup, a clockwise turn going from the top to the right. A convention is written against it. - A vertical without a CRS is kept as depth downward and said so.
Vertical::ofis unchanged;Vertical::readingandread_notedreturn aVerticalReadingwhoseVerticalBasisisCrs,NoCrs,UnreadableCrsorDeclared. The basis travels with the line (Path::vertical_basis,Path::vertical_note), andPlacedPath::newsets it withPath::with_verticalwhen the caller declares the system. A view says that the vertical was assumed instead of drawing it as if it were stated. - Placing a path without a CRS is refused (
PathRefusal::NoCrs); declaring one goes throughPlacedPath::new.
Consequences
- A caller with the producer’s documentation writes its convention once and gets the same picture every time; one without it gets a named refusal and not a plausible wrong ring.
- A convention such as the order of the axes of a vendor’s compound system is settled in a campaign on real files, never guessed by the library.
- A test that declares a convention states which reading it stands for.
- The signal on the vertical does not change a number: it adds a note that a view can show.