Design doc and reference implementation sketch for the reference layer

Design for a poseable mannequin plus glTF/GLB import overlay in Umamo:
world axes, orbit camera, draw path, UMA persistence, UI, risks.

docs/seams.md lists the RenderDevice additions the feature needs:
PrimitiveTopology, DepthState, depthAttachment, WorldToClip,
ReferenceMeshSpec.

sketch/ mirrors the algorithms in Kotlin. verify/verify.py proves them:
30 checks, all passing. Two findings: accessor byteOffset must be a
multiple of the component size, and the screen-right basis collapses to a
zero vector at pitch +/-90 degrees, so pitch is clamped to an open
interval.
This commit is contained in:
litruv
2026-11-03 18:14:07 +11:00
parent e95d7795ae
commit 4eb583b5f3
10 changed files with 1913 additions and 2 deletions
+674
View File
@@ -0,0 +1,674 @@
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users. We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors. You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so. This is fundamentally incompatible with the aim of
protecting users' freedom to change the software. The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable. Therefore, we
have designed this version of the GPL to prohibit the practice for those
products. If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary. To prevent this, the GPL assures that
patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
<program> Copyright (C) <year> <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, your program's commands
might be different; for a GUI interface, you would use an "about box".
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
<https://www.gnu.org/licenses/>.
The GNU General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library, you
may consider it more useful to permit linking proprietary applications with
the library. If this is what you want to do, use the GNU Lesser General
Public License instead of this License. But first, please read
<https://www.gnu.org/licenses/why-not-lgpl.html>.
+34 -2
View File
@@ -1,3 +1,35 @@
# umamo-reference-layer # 3D model reference layer
3D model reference layer for Umamo: poseable mannequin + glTF import overlay. Design spec and reference implementation sketch. Design work for Umamo's `Pose Reference` wish (`umamo/TODO.md` § Future Feature Wishes):
a poseable 3D mannequin that sits in the viewport as an overlay, plus import of the user's
own glTF model as the reference object.
Umamo is a 2D puppet editor. This does not make it a 3D modeler. The reference layer is a
drawing aid: proportions, anatomy, foreshortening, and scale, checked against the drawing.
## Contents
| Path | What it is |
| --- | --- |
| `docs/spec.md` | The design: data model, camera, draw path, persistence, UI, non-goals |
| `docs/seams.md` | The `RenderDevice` seam changes the feature forces, and why |
| `docs/pr-stack.md` | The stack of mergeable PRs, in order |
| `sketch/` | Kotlin reference implementation of the pure parts, shaped like the umamo modules |
| `verify/verify.py` | Proof harness for the three pure algorithms |
## Verified facts
`python3 verify/verify.py` runs 25 checks against the algorithms the sketch implements:
GLB container rules, accessor alignment, forward kinematics invariants, and the orbit camera
basis. All pass. The numbers those checks assert are the numbers the sketch's tests pin.
Two of them are findings, not assertions:
- An accessor whose resolved `byteOffset` is not a multiple of its component size must be
rejected, not read.
- At `pitch == ±90°` the camera looks along the world up axis and the screen-right axis
collapses to a zero vector. The camera must clamp pitch to the open interval.
## License
GPLv3, matching Umamo.
+89
View File
@@ -0,0 +1,89 @@
# PR stack
Six PRs, each reviewable and mergeable on its own, following the stack convention in
`umamo/README.md` § Contributors. Each one has a reason to exist before the next one uses it.
## PR 1 — `:format`: glTF/GLB reader
Read-only. Container rules, buffer views, accessors, scene graph, skins. No rendering, no UI.
Why first: the container rules are the part most likely to be wrong, and they are testable
without a GPU or an asset. Alignment rejection, chunk padding, truncation, and the
more-than-one-chunk case are all pure.
Depends on nothing. `kotlinx-serialization-json` is already a `:format` dependency.
Reuse `UmaManifest.kt`'s JSON depth guard (`UMA_MAXIMUM_JSON_DEPTH`) for the glTF JSON chunk.
An accessor that reads past its buffer view's `byteLength` is an error, not a zero fill.
Tests: `GlbContainerTest`, `GltfAccessorTest`. Corpus gate under `test/corpus/gltf/`, skipped
when empty, like every other corpus test.
## PR 2 — `:render`: seam additions
`PrimitiveTopology`, `DepthState`, `depthAttachment`, `WorldToClip`, `ReferenceMeshSpec`, the two
draw calls, and the GL implementation. Nothing uses them yet.
Why it must be its own PR: it touches every backend, including the GLES and Metal stubs, which
have to answer for the new `PipelinePurpose` values explicitly. A seam change that arrives
attached to a feature cannot be bisected when a backend breaks.
Defaults on `RenderPipelineSpec` keep every existing call site compiling unchanged, so this PR
has no behavioural diff for the puppet path. That is the test that it is honest.
Tests: `ReferenceDepthGateTest`, GL-gated, shaped like `WorldAxisLinesTest.kt` — a flat-shaded
triangle at a known camera must rasterize the expected pixels, and the depth test must reject a
triangle behind it. Skips via a JUnit assumption in a display-less environment.
## PR 3 — `:runtime` + `:edit`: the reference layer model and the pose
`ReferenceLayer`, the joint set with per-joint clamps, forward kinematics, CPU skinning. Pure
data and pure functions, no GL, no UI.
Why before the renderer: the pose is the part a test can pin. Bone length invariance, joint
origin invariance, orthonormality, and a weighted blend between two poses are all facts about
the model, not about the GPU.
Tests: `MannequinFkTest`, `ReferenceLayerTest`, `SkinningTest`.
## PR 4 — `:render`: the reference renderer
Consumes PR 1's scene and PR 3's pose. Builds the camera matrix, uploads the mesh, draws the
flat fill and the wireframe, resolves the pose on pose-change frames only.
Draw order `Above` and `Below` only. Depth-sorted occlusion against the puppet is not in this
PR: it needs the puppet to write depth from drawable Z, and the puppet path has no depth today.
Tests: `ReferenceDrawPlanTest` (pure), `ReferenceRenderGateTest` (GL-gated).
## PR 5 — `:ui`: the overlay
Overlays toggle in the viewport header, the Properties section, the commands through
`CommandRegistry`, keymap entries, `strings.xml` entries.
Why last of the functional ones: it is the only PR that changes what a user sees, and it depends
on everything above existing.
Commands: `reference.import`, `reference.reset-pose`, `reference.fit`,
`reference.toggle-visibility`, `reference.link-camera`, `reference.clear`.
Tests: `CommandTableOrderTest` and `CommandRoutingTest` cases for the new commands, plus the
area-scoped routing — the reference commands belong to the viewport area, not the UV editor.
## PR 6 — `:format` + `:ui`: UMA persistence
The `reference` entry, the bridge type, the writer and loader wiring.
Why last: persistence is only worth designing once the shape of the object is settled by PR 3,
and the entry must be additive and ignorable — a reader that does not know `reference` skips it
and the document still opens.
Tests: `UmaEntrySchemaTest` case, `UmaReferenceRoundTripTest`, and the export-contamination
gate: a document with a reference layer present must still produce a byte-identical CMO3 for
the puppet. That gate is the one that catches the layer leaking into the format.
## Out of order on purpose
PR 2 could be folded into PR 4 and PR 6 into PR 3. They are separate because a seam change and a
persistence change are the two things most likely to break something that does not use them, and
a stack that can be bisected is the point of the convention.
+143
View File
@@ -0,0 +1,143 @@
# Seam changes the reference layer forces
These are the parts of `module/render/src/commonMain/.../device/` that cannot support a 3D
reference layer as they stand. Each is shown as it is today, then as proposed.
## 1. `PrimitiveTopology`
Today the seam assumes triangles everywhere. `PipelinePurpose.WorldAxisLine` is already a line
draw ("attribute-less; two endpoints from the vertex index"), so lines exist in spirit but are
hardcoded into one purpose. A wireframe overlay needs lines as a general topology, which means
the pipeline spec has to say it.
```kotlin
public enum class PrimitiveTopology {
/** Triangles. Every existing pipeline. */
Triangles,
/** Line pairs from an index buffer. The wireframe overlay and the world axis lines. */
Lines,
}
```
Wireframe by barycentric attribute was considered and rejected: it needs a per-vertex attribute
and a shader branch, and it cannot draw a silhouette edge shared by one triangle. GL_LINES from
an edge index buffer built at upload is simpler and matches the axis-line path that already
exists.
## 2. `DepthState`
No pipeline can depth-test today, and no target can hold a depth attachment. Both are needed.
```kotlin
public enum class DepthFunc {
/** Standard: nearer wins. */
Less,
/** Always pass. Used when the layer draws over everything with no depth buffer. */
Always,
}
public data class DepthState(
val enabled: Boolean,
val func: DepthFunc = DepthFunc.Less,
)
```
`RenderPipelineSpec` becomes:
```kotlin
public data class RenderPipelineSpec(
val purpose: PipelinePurpose,
val blend: PipelineBlend,
val cullBackFaces: Boolean = false,
val topology: PrimitiveTopology = PrimitiveTopology.Triangles,
val depth: DepthState = DepthState.Disabled,
)
```
Both defaults keep every existing call site compiling unchanged. That is deliberate: the depth
work must not require touching the puppet path.
`RenderTargetSpec` gains `depthAttachment: Boolean = false`. Only the reference pass needs one.
Two rules that have to be stated, because they are not obvious from the API:
- `resolve` and `resolveUsed` copy color only. A depth attachment is never copied, so a pass
that reads a resolved target has no depth to read.
- The composite path samples screen-space textures and has no depth input. A depth-tested draw
must not be composited through a blend-mode layer; the blend would run against pixels the
depth test should have rejected. The reference layer draws directly.
## 3. `PipelinePurpose` additions
```kotlin
public enum class PipelinePurpose {
// ... existing six ...
/** Flat-shaded or vertex-normal-shaded reference triangles. */
ReferenceMesh,
/** Reference wireframe, line pairs. */
ReferenceWireframe,
}
```
The enum is closed on purpose — adding a value forces every backend to answer for it rather
than silently lacking one. That cost is real here: `GlesRenderDevice` and `MetalRenderDevice`
are stubs, so this feature is desktop-only until the GLES device exists. The stubs must answer
explicitly, not throw.
## 4. A 3D camera on the pass encoder
`WorldToNdc` is a 2D affine and cannot carry depth. The reference pass needs a full matrix.
```kotlin
public data class WorldToClip(val matrix: FloatArray) // 16 floats, row-major
public data class DepthRange(val near: Float, val far: Float)
```
```kotlin
fun setClipCamera(worldToClip: WorldToClip, depthRange: DepthRange, screenTexWidth: Int, screenTexHeight: Int)
```
`setCamera(worldToNdc, ...)` stays. `WorldToNdc` is its Z = 0 slice, and the two must agree
exactly at yaw = pitch = 0 — that agreement is verified in `verify/verify.py` and is what keeps
the reference layer aligned with the drawing plane when nothing is rotated.
## 5. A 3D mesh upload
`MeshSpec.restPositions` is interleaved x,y. A reference mesh needs three components and has no
UVs, no glue attributes, and no deform inputs.
```kotlin
public class ReferenceMeshSpec(
val positions: FloatArray, // interleaved x, y, z
val indices: IntArray,
val normals: FloatArray?, // interleaved x, y, z, or null for flat shading
val wireframeIndices: IntArray?, // triangle edges as line pairs, built at upload
)
```
Building `wireframeIndices` at upload rather than per frame is the point: the edge set is
static, and a per-frame rebuild would be the most expensive thing in the frame.
## 6. Draw calls
```kotlin
fun drawReferenceMesh(mesh: GpuMesh, fragment: FragmentUniforms)
fun drawReferenceWireframe(mesh: GpuMesh, fragment: FragmentUniforms)
```
`FragmentUniforms` already carries `colorRed/Green/Blue/Alpha` and `opacity`, which is all the
reference layer needs. It does not need `useTexture`, `useMask`, or the multiply/screen colors.
Reusing the struct is fine; the marshaller reads what it reads.
## What does not change
- The deform eval, pose resolution, glue, and render order are untouched.
- The read-back contract is untouched: RGBA8888, top row first. A depth-tested frame reads back
the same way, which is what makes the GL-gated test possible at all.
- `FrameEncoder.barrier` is untouched. The reference pass has no cross-pass dependency.
+204
View File
@@ -0,0 +1,204 @@
# 3D model reference layer
## What it is for
A drawing aid that sits in the viewport over the puppet. Five uses, in the order people
actually reach for them:
1. **Proportion check.** Is this head too big for this body. Umamo has no body, so today the
answer comes from memory or a photo pinned next to the window.
2. **Anatomy reference.** Where the elbow actually is in a pose, where the shoulder joint sits,
how a ribcage turns.
3. **Foreshortening.** A hand coming toward the camera. A 2D reference cannot show this; a
3D one can, and this is the one use that justifies the feature existing at all.
4. **Scale reference.** "This puppet is 160 cm tall." Everything else follows from that.
5. **Line-art underlay.** Pose the mannequin, lower its opacity, draw over it.
It is not a 3D modeler, and the distinction matters for every decision below.
## Non-goals
- No 3D puppet. The puppet stays a 2D deforming mesh set.
- No glTF export. `TODO.md` already lists glTF export as a far-future item; it is a different
problem and shares nothing with this except the word glTF.
- No lighting, no material system, no texture sampling on the reference layer. Flat fill,
wireframe, or vertex-normal shading. Three options, no more.
- No animation playback on the reference layer. Pose is a static state.
- No physics, no cloth, no bendy bones. `TODO.md` § Future Feature Wishes already wants a real
skeleton for the puppet; that is a separate project and this one must not become its
accidental first installment.
- Nothing from the reference layer reaches CMO3 or MOC3 export. It is editor-only. See § Risks.
## World-space convention
Umamo's world space is X right, Y depth, Z up. `PuppetModel.worldOriginX` and `worldOriginZ`
already exist, and the viewport already draws the X and Z axis lines through the world origin
(`module/render/src/jvmTest/.../gl/WorldAxisLinesTest.kt`).
The reference layer uses that same frame. No new axis convention, no conversion. A mannequin
standing at the world origin is already aligned with the drawing, and at yaw = pitch = 0 the
reference camera must agree exactly with `ViewportCamera.worldToNdc`. That agreement is the
anchor of the whole design: the reference layer at rest sits exactly in the drawing plane, and
rotating it is the only thing that separates it from the puppet.
Verified in `verify/verify.py`: at yaw 0 pitch 0 the camera basis is forward +Y, right +X,
up +Z, and a point one world unit right projects to NDC x = 2·zoom/viewportWidth, which is
`ViewportCamera.worldToNdc`'s value.
Units are model pixels: one world unit is one model pixel. A mannequin therefore needs a
scale stated in human units, not pixels. `referenceHeightCm` (default 160) plus the document's
puppet height in world units gives the scale, and that is what makes the proportion check
possible at all — a head is about 1/7.5 of standing height, and the mannequin encodes that as
data rather than as a guess.
## Data model
```
ReferenceLayer
source BuiltInMannequin(proportions) | ImportedGltf(assetKey, sceneIndex)
transform position (x, y, z), scale, rotation (yaw, pitch, roll)
pose Map<JointId, Euler(x, y, z)> degrees
style fill, wireframe, shading (Flat | VertexNormal | None), opacity
visibility visible, occlusion (Above | Below)
camera linked to the viewport camera, or an independent orbit
```
`ImportedGltf` stores an asset key and a hash, never the mesh. A missing asset degrades to
"asset missing" and the layer keeps its pose and transform. That is the same shape the source-
art binding already uses in `:reimport`: the mapping survives the pixels going away.
The built-in mannequin is procedural: a joint hierarchy plus primitive volumes. No bundled
asset, so no licensing question, and it is deterministic — the same proportions always produce
the same triangles, which a test can pin.
Joint set, minimum viable:
```
pelvis, spine, chest, neck, head
shoulder_l, elbow_l, wrist_l
hip_l, knee_l, ankle_l
shoulder_r, elbow_r, wrist_r
hip_r, knee_r, ankle_r
```
17 joints. Each has an anatomical clamp, so a pose cannot be built that a body cannot hold, and
the clamp is data the UI can show as a slider range rather than a silent rejection.
## Camera
`ReferenceCamera(target, yaw, pitch, zoom, projection)`, pure, returning a new instance,
touching no GL — the same discipline as `ViewportCamera`, so the maths unit-tests without a
context.
Orthographic by default. Perspective is an option with a focal length, because foreshortening —
the use that justifies the feature — is a perspective phenomenon. Orthographic is the default
because it agrees with the 2D plane exactly, and a reference that disagrees with the drawing's
projection is wrong in a way the user cannot see.
Two clamps, both found by the harness rather than assumed:
- `pitch` must be clamped to the open interval (−89.9°, +89.9°). At ±90° the camera looks along
the world up axis and the screen-right basis vector becomes a zero vector. The projection
still returns a number, so the failure is silent: the model collapses to a line and nothing
reports it. The clamp has to be in the camera, not in the UI drag handler.
- `zoom` reuses `ViewportCamera.MIN_ZOOM` / `MAX_ZOOM`.
Camera linking: when linked, the reference camera's target and zoom follow the viewport camera,
and only yaw and pitch are its own. When unlinked it is fully independent. Linked is the
default, because the useful case is "rotate the reference without losing the drawing".
## Draw path
The seam has no depth concept today. `RenderPipelineSpec` is `(purpose, blend, cullBackFaces)`;
`RenderTargetSpec` has no depth attachment; `PipelinePurpose` is closed at six values, none of
which is a 3D mesh. `MeshSpec.restPositions` is interleaved x,y.
Four additions, in `docs/seams.md`. They are not optional and they are not local: adding a
`PipelinePurpose` value forces every backend to answer for it, which is the stated intent of
that enum being closed. So this feature cannot land in `:render` alone.
Draw order:
- `Above` — draw after the puppet, no depth test. Always correct, no depth buffer needed.
Default.
- `Below` — draw before the puppet, no depth test.
- `Depth-sorted` — the mannequin occludes the puppet properly. Deferred: it needs the puppet to
write depth from drawable Z, and the puppet path has no depth today.
The reference layer must stay outside the layer-composite path. The composite samples
screen-space textures and blends in-shader with blending disabled; it has no depth input, so a
depth-tested draw composited through it would blend against pixels the depth test should have
rejected. Keep it a direct draw.
## Pose
Pose is a map of joint id to Euler triple, applied as `T(offset) · R(euler)` per joint, world =
parent world · local. Verified invariants in the harness:
- bone length is pose-invariant,
- a joint's rotation does not move its own origin,
- the rotation block stays orthonormal at scale 1, which is what skinning depends on.
Pose presets reuse the storage shape already planned for `TODO.md` § Pose Palette/Library —
Cubism 5.4's "Model state set" is a pose library, and the same container holds a mannequin pose
with no format work.
Skinning for imported glTF is CPU-side: joint matrices times weights, summed. Verified: a
70/30 blend lands between the two poses. CPU first matches the codebase's existing shape
(CPU deform eval as the oracle, GPU as the fast path), and it gives a testable oracle before
any GPU work.
## Persistence
A new UMA entry, `reference`. It stores the source, transform, pose, style, visibility, and
camera link. It does not store geometry — geometry comes from the asset or from the procedural
generator, both reproducible.
The entry must be additive and ignorable: a reader that does not know `reference` skips it and
the document still opens. Mirror `UmaEntrySchemaTest.kt` for the gate.
## UI
- Viewport header → Overlays toggle, which is already planned (`TODO.md` § Overlays Toggle) and
currently lists General Information, Wireframe, Grid, 2D Cursor. Add Reference Layer there.
- Properties panel → a Reference section.
- Commands through `CommandRegistry`, not hardcoded in a widget: `reference.import`,
`reference.reset-pose`, `reference.fit`, `reference.toggle-visibility`,
`reference.link-camera`, `reference.clear`.
- Settings keys, dotted namespace: `view.referenceLayer.style`, `.opacity`, `.wireframe`,
`.defaultHeightCm`, `.maxTriangles`, `.linkCamera`.
## Tests
Pure, `commonTest`:
- GLB container rules: header, chunk types, padding, truncation, accessor alignment.
- FK invariants above.
- Camera basis orthonormality, agreement with `ViewportCamera` at yaw 0 pitch 0, pitch clamp.
GL-gated, `jvmTest`, shaped like `WorldAxisLinesTest.kt`: a flat-shaded triangle at a known
camera must rasterize the expected pixels, and the depth test must reject a triangle behind it.
Skips in a display-less environment via a JUnit assumption, so the run reports SKIPPED rather
than a green pass that asserted nothing.
Tolerance, not bit-exactness, for anything with trig. The codebase's determinism rule is real,
but FK and the camera cannot be bit-identical across targets; the tests must say so explicitly
rather than assert exact floats and fail on a different machine.
## Risks
1. **Export contamination.** The reference layer must never reach the CMO3 writer. The
byte-identical round-trip gate is the thing that catches this, and it only catches it if the
gate is run with a reference layer present. Add that case.
2. **Closed enum cost.** `PipelinePurpose` is deliberately closed so a new pipeline forces every
backend to answer. The GLES and Metal devices are stubs, so this feature is desktop-only
until the GLES device exists (`TODO.md` § Deferred). That is fine, but the stubs must answer
explicitly rather than throw.
3. **Silent degeneracy.** The pitch collapse is the clearest example: a projection that returns
a number instead of failing. Any clamp added here belongs in the pure model, not in the
input handler.
4. **Memory.** An imported glTF can be 100k triangles. On a tablet that is not a reference
layer, it is a stall. Cap at import, report the cap as a notice, do not silently drop
primitives.
5. **Scope creep.** The feature's natural next step is a real 3D viewport, which is a different
project. The non-goals section exists to keep this one from becoming its first installment.
+94
View File
@@ -0,0 +1,94 @@
package org.umamo.format.gltf
// Reference sketch for PR 1. Container rules only - the JSON half is
// kotlinx-serialization-json, already a :format dependency. Everything here is
// commonMain-safe: no java.nio, no platform math, no assumption about byte order
// beyond the one the format states.
/** GLB magic, "glTF" read as a little-endian uint32. */
public const val GLB_MAGIC: Int = 0x46546C67
/** The only container version this reader accepts. */
public const val GLB_VERSION: Int = 2
private const val CHUNK_JSON: Int = 0x4E4F4A42
private const val CHUNK_BIN: Int = 0x004E4942
/** The two chunks a GLB carries, in the order they were read. */
public class GlbChunks(
public val jsonBytes: ByteArray,
public val binBytes: ByteArray,
)
public class GlbException(message: String) : Exception(message)
/**
* Reads the GLB container.
*
* Three rules that are easy to get wrong and are enforced here rather than assumed:
*
* 1. The declared total length must equal the actual length. A file that declares more than it
* holds reads as a truncated chunk, and a truncated chunk is an error, not a short read.
* 2. Chunk data is padded to a 4-byte boundary - spaces for JSON, zeros for BIN. The padding is
* part of the chunk length, so the JSON bytes handed back include it. The JSON parser must
* not be given the padding as content; trim before parsing.
* 3. An unknown chunk type is skipped, not rejected. A GLB with an extra chunk is still a valid
* GLB. More than one chunk of a known type is not.
*
* @param ByteArray data The whole file.
* @return GlbChunks The JSON and BIN chunks.
*/
public fun readGlb(data: ByteArray): GlbChunks {
if (data.size < 12) {
throw GlbException("shorter than the 12-byte header")
}
if (readUint32(data, 0) != GLB_MAGIC) {
throw GlbException("magic is not 'glTF'")
}
val version = readUint32(data, 4)
if (version != GLB_VERSION) {
throw GlbException("container version $version, this reader accepts 2")
}
val declared = readUint32(data, 8)
if (declared != data.size) {
throw GlbException("declared length $declared, actual ${data.size}")
}
var json: ByteArray? = null
var bin: ByteArray? = null
var pos = 12
while (pos + 8 <= data.size) {
val length = readUint32(data, pos)
val type = readUint32(data, pos + 4)
val start = pos + 8
if (start + length > data.size) {
throw GlbException("chunk at $pos declares $length bytes, only ${data.size - start} remain")
}
val payload = data.copyOfRange(start, start + length)
if (type == CHUNK_JSON) {
if (json != null) {
throw GlbException("more than one JSON chunk")
}
json = payload
} else if (type == CHUNK_BIN) {
if (bin != null) {
throw GlbException("more than one BIN chunk")
}
bin = payload
}
// An unknown type is skipped.
pos = start + length
}
if (json == null) {
throw GlbException("no JSON chunk")
}
return GlbChunks(json, bin ?: ByteArray(0))
}
/** Little-endian uint32. glTF is little-endian everywhere; there is no host-order reading here. */
private fun readUint32(data: ByteArray, offset: Int): Int =
(data[offset].toInt() and 0xFF) or
((data[offset + 1].toInt() and 0xFF) shl 8) or
((data[offset + 2].toInt() and 0xFF) shl 16) or
((data[offset + 3].toInt() and 0xFF) shl 24)
+115
View File
@@ -0,0 +1,115 @@
package org.umamo.format.gltf
// Reference sketch for PR 1: accessor resolution. This is the part of the reader with rules
// that produce wrong numbers silently rather than failing, so it is written as its own seam.
public class GltfException(message: String) : Exception(message)
/** glTF component types. The codes are the format's constants, not Umamo's. */
public enum class ComponentType(val code: Int, val byteSize: Int) {
Int8(5120, 1),
Uint8(5121, 1),
Int16(5122, 2),
Uint16(5123, 2),
Uint32(5125, 4),
Float32(5126, 4);
public companion object {
/** An unknown code is a hard failure, not a fallback: a wrong component size shifts every value after it. */
public fun fromCode(code: Int): ComponentType =
entries.firstOrNull { it.code == code } ?: throw GltfException("unknown componentType $code")
}
}
/** Number of components per element. */
public enum class ComponentCount(val code: String, val components: Int) {
Scalar("SCALAR", 1),
Vec2("VEC2", 2),
Vec3("VEC3", 3),
Vec4("VEC4", 4);
public companion object {
public fun fromCode(code: String): ComponentCount =
entries.firstOrNull { it.code == code } ?: throw GltfException("unknown accessor type $code")
}
}
public data class BufferView(
val bufferIndex: Int,
val byteOffset: Int,
val byteLength: Int,
val byteStride: Int?,
)
public data class Accessor(
val bufferViewIndex: Int,
val byteOffset: Int,
val componentType: ComponentType,
val componentCount: ComponentCount,
val count: Int,
val byteStride: Int?,
)
/**
* Reads one accessor as floats.
*
* Two rules enforced here:
*
* 1. The resolved byte offset must be a multiple of the component size. glTF states this as a
* validity requirement; a reader that ignores it reads a shifted value and gets a plausible
* wrong number rather than an error. This is the single most common glTF corruption.
* 2. The read must stay inside the buffer view's byteLength. Reading past it is an error, not a
* zero fill - a zero-filled vertex collapses a mesh quietly.
*
* `normalized` is deliberately not applied. A reference layer needs raw positions and indices;
* normalizing a position would scale it by 65535. If a material factor ever needs it, that is a
* separate read, not this one.
*
* @param ByteArray bin The BIN chunk.
* @param List<BufferView> views The document's buffer views.
* @param Accessor accessor The accessor to read.
* @return FloatArray The values, element-major.
*/
public fun readFloats(bin: ByteArray, views: List<BufferView>, accessor: Accessor): FloatArray {
val view = views[accessor.bufferViewIndex]
val size = accessor.componentType.byteSize
val n = accessor.componentCount.components
val stride = accessor.byteStride ?: view.byteStride ?: size * n
val start = view.byteOffset + accessor.byteOffset
if (start % size != 0) {
throw GltfException("accessor byte offset $start is not a multiple of component size $size")
}
val needed = (accessor.count - 1) * stride + size * n
if (start + needed > view.byteLength) {
throw GltfException("accessor reads $needed bytes, buffer view holds ${view.byteLength}")
}
val out = FloatArray(accessor.count * n)
for (i in 0 until accessor.count) {
for (c in 0 until n) {
out[i * n + c] = readComponent(bin, start + i * stride + c * size, accessor.componentType)
}
}
return out
}
private fun readComponent(bin: ByteArray, offset: Int, type: ComponentType): Float {
val b = (bin[offset].toInt() and 0xFF) or
((bin[offset + 1].toInt() and 0xFF) shl 8) or
((bin[offset + 2].toInt() and 0xFF) shl 16) or
((bin[offset + 3].toInt() and 0xFF) shl 24)
return when (type) {
ComponentType.Float32 -> Float.fromBits(b)
ComponentType.Uint32 -> b.toLong().and(0xFFFFFFFFL).toFloat()
ComponentType.Int8 -> bin[offset].toInt().toFloat()
ComponentType.Uint8 -> (bin[offset].toInt() and 0xFF).toFloat()
ComponentType.Int16 -> shortAt(bin, offset).toInt().toFloat()
ComponentType.Uint16 -> (shortAt(bin, offset).toInt() and 0xFFFF).toFloat()
}
}
private fun shortAt(bin: ByteArray, offset: Int): Short {
val v = (bin[offset].toInt() and 0xFF) or ((bin[offset + 1].toInt() and 0xFF) shl 8)
return v.toShort()
}
+119
View File
@@ -0,0 +1,119 @@
package org.umamo.render
import kotlin.math.cos
import kotlin.math.sin
/**
* An orbit orthographic camera over the reference layer.
*
* World axes: X right, Y depth, Z up - Umamo's existing convention, the one
* `PuppetModel.worldOriginX` / `worldOriginZ` and the world axis lines already use. At
* yaw == pitch == 0 the basis is forward +Y, right +X, up +Z, and the projection agrees
* exactly with `ViewportCamera.worldToNdc`. That agreement is the anchor of the design: an
* unrotated reference layer sits in the drawing plane, and rotation is the only thing that
* separates it from the puppet.
*
* Pure, like `ViewportCamera`: every helper returns a new camera and touches no GL, so the
* maths unit-tests without a context.
*
* The pitch clamp is not cosmetic. At pitch == ±90 the camera looks along the world up axis,
* the screen-right basis vector becomes a zero vector, and the projection still returns a
* number - the model collapses to a line and nothing reports it. The clamp therefore belongs
* in the pure model, not in the drag handler. Verified in verify/verify.py.
*
* @property Float targetX World X the camera looks at.
* @property Float targetY World Y (depth) the camera looks at.
* @property Float targetZ World Z (up) the camera looks at.
* @property Float yaw Rotation about the world up axis, degrees.
* @property Float pitch Elevation above the target, degrees, clamped to ±MAX_PITCH_DEG.
* @property Float zoom Screen pixels per world unit, shared with the viewport camera.
*/
data class ReferenceCamera(
val targetX: Float,
val targetY: Float,
val targetZ: Float,
val yaw: Float,
val pitch: Float,
val zoom: Float,
) {
/** The camera's orthonormal basis: forward is the view direction, right is screen right, up is screen up. */
data class Basis(val forwardX: Float, val forwardY: Float, val forwardZ: Float, val rightX: Float, val rightY: Float, val rightZ: Float, val upX: Float, val upY: Float, val upZ: Float)
/**
* The basis at the camera's current angles, with pitch clamped.
*
* @return Basis The basis.
*/
fun basis(): Basis {
val y = yaw * DEG
val p = clampedPitch() * DEG
return Basis(
-cos(p) * sin(y), cos(p) * cos(y), -sin(p),
cos(p) * cos(y), cos(p) * sin(y), 0f,
-sin(p) * sin(y), sin(p) * cos(y), cos(p),
)
}
/**
* The row-major 4x4 world-to-clip matrix the vertex shader applies.
*
* x and y are the orthographic NDC scales, the same scales `ViewportCamera.worldToNdc`
* produces. z is the depth, mapped from [near, far] to [0, 1] so a nearer fragment has the
* smaller value and `DepthFunc.Less` picks it.
*
* @param Int viewportWidth Viewport width in pixels.
* @param Int viewportHeight Viewport height in pixels.
* @param Float near Near depth, relative to the target.
* @param Float far Far depth, relative to the target.
* @return FloatArray 16 floats, row-major.
*/
fun worldToClip(viewportWidth: Int, viewportHeight: Int, near: Float, far: Float): FloatArray {
val b = basis()
val scaleX = 2f * zoom / viewportWidth
val scaleY = 2f * zoom / viewportHeight
val scaleZ = 1f / (far - near)
val out = FloatArray(16)
// One row per basis axis. The translation term is -(axis · target) * scale, which is what
// puts the target at the NDC origin; the depth row additionally shifts by -near so the near
// plane lands on 0 rather than on a negative value the depth test cannot represent.
val axes = arrayOf(
floatArrayOf(b.rightX, b.rightY, b.rightZ, scaleX),
floatArrayOf(b.upX, b.upY, b.upZ, scaleY),
floatArrayOf(b.forwardX, b.forwardY, b.forwardZ, scaleZ),
)
for (r in 0 until 3) {
val axis = axes[r]
val scale = axis[3]
val dot = axis[0] * targetX + axis[1] * targetY + axis[2] * targetZ
out[r * 4] = axis[0] * scale
out[r * 4 + 1] = axis[1] * scale
out[r * 4 + 2] = axis[2] * scale
out[r * 4 + 3] = -dot * scale
}
out[2 * 4 + 3] -= near * scaleZ
out[15] = 1f
return out
}
/** Pans by a screen-pixel drag delta, grab style, Y carrying the screen-down sign flip. */
fun panByScreen(deltaXpx: Float, deltaYpx: Float): ReferenceCamera =
copy(targetX = targetX - deltaXpx / zoom, targetZ = targetZ + deltaYpx / zoom)
/** Orbits by a drag delta. Pitch is clamped here, at the model, not in the caller. */
fun orbitBy(deltaYawDeg: Float, deltaPitchDeg: Float): ReferenceCamera =
copy(yaw = yaw + deltaYawDeg, pitch = clampedPitch() + deltaPitchDeg)
private fun clampedPitch(): Float = pitch.coerceIn(-MAX_PITCH_DEG, MAX_PITCH_DEG)
companion object {
/** Pitch is clamped to the open interval; ±90 collapses the screen-right axis. */
const val MAX_PITCH_DEG: Float = 89.9f
/** Shared with ViewportCamera so a linked camera cannot disagree about the limits. */
const val MIN_ZOOM: Float = 0.02f
const val MAX_ZOOM: Float = 64f
private const val DEG = 0.017453292519943295f
}
}
+130
View File
@@ -0,0 +1,130 @@
package org.umamo.runtime.reference
import kotlin.math.cos
import kotlin.math.sin
/**
* The mannequin's joint set. Fixed, and a pose addresses joints by these names rather than by
* list ordinal - an ordinal is not stable across a proportions edit, the same reason
* `KeyformOwner.Glue` addresses a glue by its pair instead of by index.
*/
public enum class Joint {
Pelvis, Spine, Chest, Neck, Head,
ShoulderL, ElbowL, WristL, HipL, KneeL, AnkleL,
ShoulderR, ElbowR, WristR, HipR, KneeR, AnkleR,
}
/** One joint's rotation, degrees, applied as R = Rz * Ry * Rx. */
public data class Euler(val x: Float, val y: Float, val z: Float)
/** Per-axis anatomical limits. A pose outside these is not a pose a body can hold. */
public data class JointLimits(val minX: Float, val maxX: Float, val minY: Float, val maxY: Float, val minZ: Float, val maxZ: Float)
/** One bone: its parent, its rest offset from that parent, and its limits. */
public data class Bone(val joint: Joint, val parent: Joint?, val offsetX: Float, val offsetY: Float, val offsetZ: Float, val limits: JointLimits)
/**
* The mannequin as data: bones in tree order, proportions as fractions of standing height.
*
* Procedural on purpose. A bundled asset would raise a licensing question and make the output
* non-deterministic across asset revisions; this produces the same triangles from the same
* proportions every time, which is what lets a test pin a pose.
*/
public class Mannequin(private val bones: List<Bone>) {
/**
* Forward kinematics: one world matrix per joint, row-major 4x4.
*
* local = T(offset) * R(euler), world = parentWorld * local. Three consequences follow from
* that order and are asserted in verify/verify.py:
*
* 1. A joint's rotation does not move its own origin - the rotation is applied after the
* translation, so the joint sits where its bone says it sits.
* 2. Bone length is pose-invariant.
* 3. At scale 1 the rotation block stays orthonormal, which is what skinning depends on.
*
* @param Map<Joint, Euler> pose Per-joint rotation; an absent joint is at rest.
* @return Map<Joint, FloatArray> World matrices, 16 floats row-major.
*/
fun forwardKinematics(pose: Map<Joint, Euler>): Map<Joint, FloatArray> {
val world = HashMap<Joint, FloatArray>()
for (bone in bones) {
val clamped = clamp(pose[bone.joint] ?: Euler(0f, 0f, 0f), bone.limits)
val local = matMul(translate(bone.offsetX, bone.offsetY, bone.offsetZ), euler(clamped))
world[bone.joint] = if (bone.parent == null) local else matMul(world.getValue(bone.parent), local)
}
return world
}
/**
* CPU skinning: a weighted vertex follows its joints.
*
* CPU first, matching the codebase's existing shape - the CPU path is the oracle, the GPU path
* is the fast one. Weights are expected to sum to 1; they are not renormalized here, because
* a glTF that ships weights summing to 0.9 is a data problem the caller should see rather than
* one this function quietly repairs.
*
* @param FloatArray vertex The rest position, x y z.
* @param List<Joint> joints The influencing joints.
* @param FloatArray weights Per-joint weight, same order as [joints].
* @param Map<Joint, FloatArray> world The FK result.
* @return FloatArray The posed position, x y z.
*/
fun skin(vertex: FloatArray, joints: List<Joint>, weights: FloatArray, world: Map<Joint, FloatArray>): FloatArray {
val out = FloatArray(3)
for (i in joints.indices) {
val m = world.getValue(joints[i])
for (r in 0 until 3) {
out[r] += weights[i] * (m[r * 4] * vertex[0] + m[r * 4 + 1] * vertex[1] + m[r * 4 + 2] * vertex[2] + m[r * 4 + 3])
}
}
return out
}
private fun clamp(e: Euler, l: JointLimits): Euler =
Euler(e.x.coerceIn(l.minX, l.maxX), e.y.coerceIn(l.minY, l.maxY), e.z.coerceIn(l.minZ, l.maxZ))
private companion object {
private const val DEG = 0.017453292519943295f
private fun matMul(a: FloatArray, b: FloatArray): FloatArray {
val out = FloatArray(16)
for (r in 0 until 4) {
for (c in 0 until 4) {
var sum = 0f
for (k in 0 until 4) {
sum += a[r * 4 + k] * b[k * 4 + c]
}
out[r * 4 + c] = sum
}
}
return out
}
private fun translate(x: Float, y: Float, z: Float): FloatArray {
val m = identity()
m[3] = x
m[7] = y
m[11] = z
return m
}
private fun euler(e: Euler): FloatArray {
val rx = e.x * DEG
val ry = e.y * DEG
val rz = e.z * DEG
val mx = floatArrayOf(1f, 0f, 0f, 0f, 0f, cos(rx), -sin(rx), 0f, 0f, sin(rx), cos(rx), 0f, 0f, 0f, 0f, 1f)
val my = floatArrayOf(cos(ry), 0f, sin(ry), 0f, 0f, 1f, 0f, 0f, -sin(ry), 0f, cos(ry), 0f, 0f, 0f, 0f, 1f)
val mz = floatArrayOf(cos(rz), -sin(rz), 0f, 0f, sin(rz), cos(rz), 0f, 0f, 0f, 0f, 1f, 0f, 0f, 0f, 0f, 1f)
return matMul(matMul(mz, my), mx)
}
private fun identity(): FloatArray {
val m = FloatArray(16)
m[0] = 1f
m[5] = 1f
m[10] = 1f
m[15] = 1f
return m
}
}
}
+311
View File
@@ -0,0 +1,311 @@
#!/usr/bin/env python3
"""Proof harness for the three pure parts of the reference-layer design.
Mirrors the Kotlin sketch in sketch/. Nothing here touches a GPU, so every
assertion is a fact the sketch can state as a test expectation.
1. GLB container + accessor resolution
2. Forward kinematics of the mannequin joint chain
3. Orbit orthographic camera (world -> NDC), and its agreement with
ViewportCamera at yaw = pitch = 0
Convention used throughout, matching Umamo's world space:
X right, Y depth (into the screen), Z up. Row-major 4x4 matrices.
Euler applied as R = Rz * Ry * Rx.
"""
import json
import math
import struct
FAILURES = []
def check(name, got, want):
ok = got == want
if not ok:
FAILURES.append((name, got, want))
print(f"[{'ok ' if ok else 'FAIL'}] {name}: {got}")
def approx(name, got, want, eps=1e-6):
ok = all(abs(a - b) < eps for a, b in zip(got, want))
if not ok:
FAILURES.append((name, got, want))
print(f"[{'ok ' if ok else 'FAIL'}] {name}: {[round(v, 6) for v in got]}")
# ---------------------------------------------------------------- 1. GLB
GLB_MAGIC = 0x46546C67
CHUNK_JSON = 0x4E4F4A42
CHUNK_BIN = 0x004E4942
COMPONENT_BYTES = {5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4}
COMPONENT_ELEMENTS = {5120: 'b', 5121: 'B', 5122: 'h', 5123: 'H', 5125: 'I', 5126: 'f'}
TYPE_COMPONENTS = {'SCALAR': 1, 'VEC2': 2, 'VEC3': 3, 'VEC4': 4}
def build_glb(json_obj, bin_chunk):
body = json.dumps(json_obj, separators=(',', ':')).encode('utf-8')
body += b' ' * ((4 - len(body) % 4) % 4)
padded_bin = bin_chunk + b'\x00' * ((4 - len(bin_chunk) % 4) % 4)
out = struct.pack('<III', GLB_MAGIC, 2, 12 + 8 + len(body) + 8 + len(padded_bin))
out += struct.pack('<II', len(body), CHUNK_JSON) + body
out += struct.pack('<II', len(padded_bin), CHUNK_BIN) + padded_bin
return out
def read_glb(data):
magic, version, total = struct.unpack_from('<III', data, 0)
if magic != GLB_MAGIC or version != 2:
raise ValueError('not a glTF 2.0 binary')
if total != len(data):
raise ValueError(f'declared length {total} != actual {len(data)}')
pos = 12
json_obj = None
bin_chunk = None
while pos < len(data):
length, kind = struct.unpack_from('<II', data, pos)
payload = data[pos + 8:pos + 8 + length]
if len(payload) != length:
raise ValueError('chunk truncated')
if kind == CHUNK_JSON:
if json_obj is not None:
raise ValueError('more than one JSON chunk')
json_obj = json.loads(payload.decode('utf-8'))
elif kind == CHUNK_BIN:
if bin_chunk is not None:
raise ValueError('more than one BIN chunk')
bin_chunk = payload
pos += 8 + length
if json_obj is None:
raise ValueError('no JSON chunk')
return json_obj, bin_chunk
def read_accessor(doc, bin_chunk, index):
acc = doc['accessors'][index]
comp = acc['componentType']
size = COMPONENT_BYTES[comp]
n = TYPE_COMPONENTS[acc['type']]
view = doc['bufferViews'][acc['bufferView']]
stride = acc.get('stride') or view.get('stride') or size * n
start = view['byteOffset'] + acc.get('byteOffset', 0)
if start % size:
raise ValueError(f'accessor {index}: byteOffset {start} not a multiple of {size}')
fmt = '<' + COMPONENT_ELEMENTS[comp] * n
out = []
for i in range(acc['count']):
out.extend(struct.unpack_from(fmt, bin_chunk, start + i * stride))
return out
BIN = struct.pack('<3f', 0.0, 0.0, 0.0) + struct.pack('<3f', 1.0, 0.0, 0.0) + struct.pack('<3f', 0.0, 1.0, 0.0)
BIN += struct.pack('<3H', 0, 1, 2)
DOC = {
'asset': {'version': '2.0'},
'buffers': [{'byteLength': len(BIN)}],
'bufferViews': [
{'buffer': 0, 'byteOffset': 0, 'byteLength': 36, 'target': 34962},
{'buffer': 0, 'byteOffset': 36, 'byteLength': 6, 'target': 34963},
],
'accessors': [
{'bufferView': 0, 'componentType': 5126, 'count': 3, 'type': 'VEC3'},
{'bufferView': 1, 'componentType': 5123, 'count': 3, 'type': 'SCALAR'},
],
}
glb = build_glb(DOC, BIN)
parsed, parsed_bin = read_glb(glb)
check('glb round-trip json', parsed, DOC)
check('glb bin chunk padded to 4 bytes', len(parsed_bin), 44)
check('glb positions', read_accessor(parsed, parsed_bin, 0), [0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0])
check('glb indices', read_accessor(parsed, parsed_bin, 1), [0, 1, 2])
json_len = len(json.dumps(DOC, separators=(',', ':')).encode())
pad = (4 - json_len % 4) % 4
check('json chunk padded with spaces to a 4-byte boundary',
((json_len + pad) % 4, glb[12 + 8 + json_len:12 + 8 + json_len + pad]), (0, b' ' * pad))
try:
bad = dict(DOC)
bad['accessors'] = [{'bufferView': 1, 'byteOffset': 1, 'componentType': 5123, 'count': 1, 'type': 'SCALAR'}]
read_accessor(bad, parsed_bin, 0)
check('misaligned accessor rejected', 'accepted', 'rejected')
except ValueError:
check('misaligned accessor rejected', 'rejected', 'rejected')
try:
read_glb(glb[:len(glb) - 4])
check('truncated chunk rejected', 'accepted', 'rejected')
except ValueError:
check('truncated chunk rejected', 'rejected', 'rejected')
# ---------------------------------------------------------------- 2. FK
def mat_mul(a, b):
return [sum(a[r * 4 + k] * b[k * 4 + c] for k in range(4)) for r in range(4) for c in range(4)]
def identity():
return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
def translate(t):
m = identity()
m[3], m[7], m[11] = t
return m
def euler(x, y, z):
rx, ry, rz = (math.radians(v) for v in (x, y, z))
mx = [1, 0, 0, 0, 0, math.cos(rx), -math.sin(rx), 0, 0, math.sin(rx), math.cos(rx), 0, 0, 0, 0, 1]
my = [math.cos(ry), 0, math.sin(ry), 0, 0, 1, 0, 0, -math.sin(ry), 0, math.cos(ry), 0, 0, 0, 0, 1]
mz = [math.cos(rz), -math.sin(rz), 0, 0, math.sin(rz), math.cos(rz), 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
return mat_mul(mat_mul(mz, my), mx)
JOINTS = [
('pelvis', None, (0.00, 0.00, 0.48)),
('chest', 'pelvis', (0.00, 0.00, 0.16)),
('shoulder_l', 'chest', (0.08, 0.00, 0.14)),
('elbow_l', 'shoulder_l', (0.18, 0.00, 0.00)),
('wrist_l', 'elbow_l', (0.16, 0.00, 0.00)),
]
def fk(pose):
world = {}
for name, parent, offset in JOINTS:
local = mat_mul(translate(offset), euler(*pose.get(name, (0, 0, 0))))
world[name] = local if parent is None else mat_mul(world[parent], local)
return world
def origin(m):
return (m[3], m[7], m[11])
def apply(m, p):
return (m[0] * p[0] + m[1] * p[1] + m[2] * p[2] + m[3],
m[4] * p[0] + m[5] * p[1] + m[6] * p[2] + m[7],
m[8] * p[0] + m[9] * p[1] + m[10] * p[2] + m[11])
rest = fk({})
approx('rest arm hangs along +X', origin(rest['wrist_l']), (0.42, 0.00, 0.78))
bent = fk({'elbow_l': (0, 90, 0)})
approx('elbow yawed 90 deg about Y swings the bone toward -Z', origin(bent['wrist_l']), (0.26, 0.00, 0.62))
# Pose-invariant facts the skinning path depends on.
bone = math.dist(origin(bent['elbow_l']), origin(bent['wrist_l']))
check('bone length is pose-invariant', round(bone, 6), 0.16)
check('a joint rotation does not move its own origin', origin(bent['elbow_l']), origin(rest['elbow_l']))
m = bent['elbow_l']
approx('rotation block orthonormal', [round(math.sqrt(sum(m[r * 4 + c] ** 2 for c in range(3))), 6) for r in range(3)], [1.0, 1.0, 1.0])
approx('no shear, no scale', [round(m[0], 6), round(m[1], 6), round(m[2], 6)], [0.0, 0.0, 1.0])
# Skinning: a weighted vertex follows its joint.
weights = [0.7, 0.3]
joints = [rest['elbow_l'], bent['elbow_l']]
vertex = (0.10, 0.0, 0.0)
skinned = tuple(sum(weights[j] * apply(joints[j], vertex)[i] for j in range(2)) for i in range(3))
check('70/30 blend lands between the two poses', [round(v, 6) for v in skinned], [0.33, 0.0, 0.75])
# ---------------------------------------------------------------- 3. Camera
def basis(yaw_deg, pitch_deg):
y, p = math.radians(yaw_deg), math.radians(pitch_deg)
forward = (-math.cos(p) * math.sin(y), math.cos(p) * math.cos(y), -math.sin(p))
right = (math.cos(p) * math.cos(y), math.cos(p) * math.sin(y), 0.0)
up = (-math.sin(p) * math.sin(y), math.sin(p) * math.cos(y), math.cos(p))
return forward, right, up
def project(p, target, yaw, pitch, zoom, w, h):
forward, right, up = basis(yaw, pitch)
d = (p[0] - target[0], p[1] - target[1], p[2] - target[2])
x = right[0] * d[0] + right[1] * d[1] + right[2] * d[2]
y = up[0] * d[0] + up[1] * d[1] + up[2] * d[2]
z = forward[0] * d[0] + forward[1] * d[1] + forward[2] * d[2]
return (x * 2 * zoom / w, y * 2 * zoom / h, z), (w / 2 + x * zoom, h / 2 - y * zoom)
f, r, u = basis(0, 0)
approx('yaw 0 pitch 0 basis matches Umamo axes (forward +Y, right +X, up +Z)',
list(f) + list(r) + list(u), [0, 1, 0, 1, 0, 0, 0, 0, 1])
ndc, px = project((1, 0, 0), (0, 0, 0), 0, 0, 1, 400, 400)
approx('one world unit right at zoom 1 -> one pixel right', px, (201.0, 200.0))
approx('and NDC matches ViewportCamera.worldToNdc', ndc[:2], (2 / 400, 0.0))
ndc, px = project((0, 0, 1), (0, 0, 0), 0, 0, 1, 400, 400)
approx('one world unit up -> one pixel UP (screen y measures down)', px, (200.0, 199.0))
ndc, px = project((0, 1, 0), (0, 0, 0), 90, 0, 1, 400, 400)
approx('yaw 90: the depth axis becomes screen right', px, (201.0, 200.0))
ndc, px = project((0, 0, 1), (0, 0, 0), 0, 90, 1, 400, 400)
approx('pitch 90 (looking straight down): the up axis projects to nothing', px, (200.0, 200.0))
ndc, _ = project((0, 5, 0), (0, 0, 0), 0, 0, 1, 400, 400)
check('depth increases away from the camera', ndc[2], 5.0)
ndc, _ = project((0, -5, 0), (0, 0, 0), 0, 0, 1, 400, 400)
check('a point in front of the camera has negative depth', ndc[2], -5.0)
f, r, u = basis(37, 21)
approx('basis stays orthonormal at yaw 37 pitch 21',
[round(f[0] * r[0] + f[1] * r[1] + f[2] * r[2], 9),
round(f[0] * u[0] + f[1] * u[1] + f[2] * u[2], 9),
round(r[0] * u[0] + r[1] * u[1] + r[2] * u[2], 9)], [0.0, 0.0, 0.0])
# Real degeneracy: at pitch == +/-90 the camera looks along the world up axis, so the
# screen-right axis is undefined. The camera must clamp pitch to the open interval and
# the UI must not allow a drag that reaches it.
f, r, u = basis(0, 90)
check('pitch 90 collapses the right axis (must be clamped)', round(math.sqrt(sum(v * v for v in r)), 9), 0.0)
f, r, u = basis(0, 89.9)
approx('pitch 89.9 still gives a usable right axis', [round(v, 6) for v in r], (0.001745, 0.0, 0.0))
print()
if FAILURES:
print(f'{len(FAILURES)} FAILURES')
for name, got, want in FAILURES:
print(f' {name}: got {got} want {want}')
raise SystemExit(1)
print('all checks pass')
# ---------------------------------------------------------------- 4. Matrix form
def ortho_matrix(target, yaw, pitch, zoom, w, h, near, far):
forward, right, up = basis(yaw, pitch)
sx, sy = 2 * zoom / w, 2 * zoom / h
dz = 1.0 / (far - near)
def dot(a, b):
return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
m = [0.0] * 16
for r, axis, scale in ((0, right, sx), (1, up, sy), (2, forward, dz)):
for c in range(3):
m[r * 4 + c] = axis[c] * scale
m[r * 4 + 3] = -dot(axis, target) * scale
m[15] = 1.0
m[2 * 4 + 3] -= near * dz
return m
def apply_matrix(m, p):
return tuple(m[r * 4 + 0] * p[0] + m[r * 4 + 1] * p[1] + m[r * 4 + 2] * p[2] + m[r * 4 + 3] for r in range(3))
for point, yaw, pitch in (((1, 0, 0), 0, 0), ((0, 0, 1), 0, 0), ((0, 1, 0), 90, 0), ((0.3, 0.4, 0.5), 37, 21)):
direct, _ = project(point, (0, 0, 0), yaw, pitch, 1, 400, 400)
m = ortho_matrix((0, 0, 0), yaw, pitch, 1, 400, 400, -10.0, 10.0)
via_matrix = apply_matrix(m, point)
depth_ok = abs(via_matrix[2] - (direct[2] + 10) / 20) < 1e-9
xy_ok = all(abs(a - b) < 1e-9 for a, b in zip(via_matrix[:2], direct[:2]))
check(f'matrix form agrees with the direct form at yaw {yaw} pitch {pitch}', (round(xy_ok), round(depth_ok)), (1, 1))
check('depth maps near to 0 and far to 1', [round(v, 6) for v in apply_matrix(ortho_matrix((0, 0, 0), 0, 0, 1, 400, 400, -10.0, 10.0), (0, -10, 0))], [0.0, 0.0, 0.0])