Zensical docs - #85
Conversation
tlambert03
left a comment
tlambert03
left a comment
There was a problem hiding this comment.
the plumbing looks great here. Feel free to move over to zensical whenever you want (I don't need to sign off on that).
Some of the even docs still strike me as a bit WIP, and could perhaps be omitted (or at least, given the relative lack of overview docs, they are very visible at the moment, and they feel slightly more like "internal discussions" than things that a new user needs to see in the first couple paragraphs)
|
|
||
| A scene isn't fully described by its visual state alone - how it evolves in response to user input is part of what the scene *is*, and expressing that declaratively would be a natural completion of `scenex`'s design. **No general solution to this has been found yet**: updating a text label when the user mouses over a point, for instance, is far easier to express as an algorithm than as a declarative specification. There is also a structural problem, as some fields only make sense in context of others; an orbit center has no meaning unless the camera controller is set to orbit, and encoding that dependency cleanly in a declarative model is awkward. |
There was a problem hiding this comment.
this is the only paragraph/section that I find a little funny. I see where you're going with it, but I think it leaks a bit too much about the internal thought process.
the phrase "A scene isn't fully described by its visual state alone" gave me pause... like "wait: isn't it?" ... I do see what you're going for, but in the conventional MVC paradigm, what you're describing next (how it responds to user input) is the Controller part, not the Model part (and the model is the state, and it is a full description). Yes, it's true that we would also like to serialize things like the camera controller, and yes, that part still needs work.... but I would just leave out the whole "no general solution" part. It makes it sound too much like a fundamental problem, as opposed to something for which we just haven't nailed down the API.
There is also a structural problem, as some fields only make sense in context of others; an orbit center has no meaning unless the camera controller is set to orbit, and encoding that dependency cleanly in a declarative model is awkward.
I don't really understand this. Yes, not all camera controllers have an orbit center, but in a hierarchical model where the controller is a union, there isn't a structural problem, it's just an acknowledgment that not all members of the controller union have a "center", perhaps?
class Scene:
camera: Camera
class Camera:
controller: OrbitController | PanZoomController
class OrbitController:
center: tupleanyway, I don't think there's a fundamental awkwardness here, (even if there is a current awkwardness in the API). So I would just leave this out of the docs. Makes more sense as a todo item in the github issues.
Yes, there will likely be some imperative callback-based action for custom user intentions (when I click on this, I want that to happen). So I see the general point being made here... but i'm not sure we're ready to codify these points as first class "scenex principles" that get top billing in the docs.
There was a problem hiding this comment.
but i'm not sure we're ready to codify these points as first class "scenex principles" that get top billing in the docs
Yeah, I do think you're right 👍 . I think I'll remove this section for the first cut of this document
| Where a filter should live follows from the nature of the event. Mouse events carry a canvas position and are naturally handled at the `View` level. Because `scenex` scenes are always 3D - even when displaying 2D data - custom mouse interaction code typically centers on rays: the view has the camera context needed to unproject a 2D canvas position into a world-space ray, and that ray is the natural representation for querying which objects are under the cursor. Keyboard events carry no position and can't be routed to a particular view, so they belong at the `Canvas` level. | ||
|
|
||
| !!! note "Why no node-level filters?" | ||
| Event filters are intentionally not placed on individual nodes. Part of this is to minimize API in the absence of a compelling use case; part is that node-level routing would require careful design to preserve performance - computing intersections against complex geometry on every event is not something you want to do naively. |
There was a problem hiding this comment.
if there is no compelling use case... then why have a "why no node-level filters" section at all? What prompted you to include this section if you don't think there are compelling use cases? who is the theoretical asker of this question?
There was a problem hiding this comment.
who is the theoretical asker of this question?
It's me, I'm the one who still thinks about adding them 😆
But, as I mentioned above, I'll remove this section from the docs for now, ad keep thinking about them.
Git on Windows missed it
2 participants
This PR refactors the documentation to use Zensical over Mkdocs and generally adds more documentation (including installation instructions and examples)
It's still a draft, but nice to get feedback as it develops
cc @tlambert03