“E. coli chemotaxis: the baffling intelligence of a single cell” by James Somers\n\nSince reading \"I should have loved biology\", I try to read everything James Somers writes. That essay introduced me to David Goodsell's amazing book The Machinery of Life!\nand Edwin Morris is a wonderful article about how E. coli bacteria sense and navigate their world, looking for nutrients. Newcomers should find it friendly, but the interactive diagrams alone should make it interesting to anyone.
\nThe article is wide in scope, covering, for instance, receptors, and what it’s like inside the cell. It meanders into bacterial individuality and how we discover these things in biology. The diagrams are pretty good, and some of them are interactive! It ends with an annotated bibliography.\n\nAnnotated bibliographies are undervalued and should be more popular.\n
\nI often interactively rebase git commits at the command line. The editor shows a list of commits. Each entry has one of a few actions. For example, “pick” means to leave the commit alone, while “squash” or “fixup” will combine a commit with another. If you reorder the lines, you reorder the commits.
\nIf you delete a line from the rebase list, git quietly drops that commit, removing those changes–by default, at least. There’s a configuration option, rebase.missingCommitsCheck, that controls what happens.
\n\n\n\nIf set to “warn”,
\ngit rebase -iwill print a warning if some commits are removed (e.g. a line was deleted), however the rebase will still proceed. If set to “error”, it will print the previous warning and stop the rebase,git rebase --edit-todocan then be used to correct the error. If set to “ignore”, no checking is done. To drop a commit without warning or error, use the drop command in the todo list. Defaults to “ignore”.
Setting rebase.missingCommitsCheck to “error” means I need to use the word “drop” to remove a commit on purpose. If I delete a line while rebasing, git will just print an error. Great!
You can set rebase.missingCommitsCheck=\"error\" by running git config --global rebase.missingCommitsCheck error in your terminal.\n\nThere are other ways to set configuration options, and the git book has a gentle introduction to configuring git.\n
I added rebase.missingCommitsCheck=\"error\" to my gitconfig years ago, as soon as I found out about it.\n\nThe missing commits check was added to Git at the end of June 2015, by Galan Rémi. Thanks!\nRecently, I saw the error for the first time, and I was inspired to post this tip. It took an untold number of rebases, but it actually did save me from accidentally dropping a commit!
Editing takes me a long time. Having a checklist and guidelines makes me faster. I like to collect folks’ personal writing guidelines, style guides, and their reasons to write. I found them helpful when writing my own. Some of these may be helpful for yours, too.
\nSome of these guidelines, I took from other folks. Some come from deep convictions. If I don’t follow those, you could take that as a sign that I’m being forced to write under duress or have been replaced by an impostor. Others, I view only as suggestions and gentle reminders.
\n\n\n[…] your lead must capture the reader immediately and force him to keep reading. It must cajole him with freshness, or novelty, or paradox, or humor, or surprise, or with an unusual idea, or an interesting fact, or a question. Anything will do, as long as it nudges his curiosity and tugs at his sleeve.
\nNext the lead must do some real work. It must provide hard details that tell the reader why the piece was written and why he ought to read it. But don’t dwell on the reason. Coax the reader a little more; keep him inquisitive.
\nContinue to build. Every paragraph should amplify the one that preceded it. Give more thought to adding solid detail and less to entertaining the reader. But take special care with the last sentence of each paragraph—it’s the crucial springboard to the next paragraph. Try to give that sentence an extra twist of humor or surprise, like the periodic “snapper” in the routine of a stand-up comic. Make the reader smile and you’ve got him for at least one more paragraph.
\n
Some of these resources have been used to create this checklist. Others, I still need to review.
\n\n![\"A](\"https://www.atomwolf.org/img/tom-critchlow-how-to-write-a-good-blog-post-JZcu1X0OMf-256w.jpeg\")
Tom Critchlow’s “Vince McMahon Reaction” with “Here’s a quick riff”, “About a line of inquiry that’s alive for me”, “This post poses more questions than answers”, “With some real texture from my own experiences”, and “Here’s a quick drawing I made”.
\nOutlines are key to discerning details in 3D CAD models. Let’s compare the modeling view from Fusion 360 with a render from model-viewer:
\n![\"A](\"https://www.atomwolf.org/img/comparing-fusion-360-and-model-viewer-hUS_QpJiqD-256w.jpeg\")
Comparison of CAD modeling view (top) from Fusion 360 and a rendered view (bottom) from model-viewer
\nThe same model looks different, even ignoring the slight camera position difference due to manual positioning. The lighting and shadows are different, the materials look different, and the colors are different. The perspective is different. Even if I adjusted the lighting, added textures, and used realistic material settings, I’d prefer looking at details in the CAD view because of the outlines.\n\nI've written about this elsewhere in this series, including Experimenting with CAD models in model-viewer.\n
\nCould I add outlines? Maybe! I didn’t know anything about how model-viewer worked. I browsed the documentation around extensions and modifications, then set the project aside to leave an opening for inspiration.
\nA few weeks later, I ran into an in-depth article about creating a post-processing effect inspired by the French artist Mœbius.
\n![\"Illustration](\"https://www.atomwolf.org/img/voyagehermes-2-m%C5%93bius-rjf1BBI_zJ-256w.jpeg\")
Plate 2 of Voyage d’Hermès, by Mœbius. Image from Sci-Fi-O-Rama.
\nThis article builds a shader, step-by-step, to add outlines, adjust shadows, and create a hand-drawn appearance to a rendered scene.
\nTo extend model-viewer, you can build on its foundation, three.js, or use model-viewer-effects, which adds post-processing effects. The article used react-three-fiber, a library that connects React to three.js! I couldn’t copy-and-paste the code samples—I couldn’t find an example for model-viewer-effects using a custom shader—but this was exactly the inspiration I needed.
\nI couldn’t find a demo with a custom shader and model-viewer, so I needed to create one. Per the documentation, I set up postprocessing and model-viewer-effects. model-viewer-effect’s documentation on custom effects aims folks at the Postprocessing Custom Effects wiki page. After reading and re-reading the Custom Effects wiki page, I had a small understanding of how it works.
\nA scene is rendered and given to the custom effects. The effect runs C-like code for each pixel of the source image, outputting a pixel used for the output image.
\nWith much effort, I had the skeleton of a custom effect rigged up to model-viewer. I was able to use it to add a partial outline to the model. This was a promising start, but I couldn’t make any improvements. I needed a deeper understanding.
\nWebGL is a JavaScript API that uses OpenGL ES for high-performance 2D and 3D graphics rendering in the browser.
\nThree.js (GitHub) is a JavaScript library that usually uses WebGL for rendering.
\nmodel-viewer (GitHub) is a JavaScript library and Web Component that uses three.js to display 3D models in the browser.
\nThe Poimandres postprocessing library adds post-processing effects to three.js.
\nmodel-viewer-effects (GitHub) is a library and Web Component that uses the postprocessing library to add effects to model-viewer.
\nPost-processing involves rendering a scene to an intermediate buffer before applying effects. Some effects can be applied directly to the intermediate render. Other effects are more complex, needing multiple passes or additional information.
\n\nOpenGL renders images using a rendering pipeline.\n\nThe Khronos Group will remind you that an OpenGL implementation renders images, while OpenGL is only a specification and an API definition for rendering.\nSome pipeline steps run programs called shaders. There are different types of shaders, like vertex shaders, which run for each vertex of the geometry, and fragment shaders, which run for each fragment, which is almost the same as a pixel. Shaders vary, but the prototypical vertex shader transforms a vertex’s 3D coordinates to a 2D screen position, and the prototypical fragment shader sets the color of a pixel. OpenGL shaders are typically written in OpenGL Shading Language (GLSL), similar to C.
\nThere are many ways to make outlines in 3D graphics.\n\nSee 5 ways to draw an outline and Generating Beautiful 3D Outlines, for instance.\nOne method uses a fragment shader. Pixel-by-pixel, it looks for edges and draws outlines on the detected edges. It uses different versions of the scene to detect more edges.
\nBased on advice from some of the articles I had found, I started with a grayscale version of the rendered scene.
\n![\"A](\"https://www.atomwolf.org/img/luma-qas3qVzgXW-256w.webp\")
\n The grayscale version of the rendered scene's colors
\nI use the Sobel operator to detect edges. For each point in the image, the Sobel operator looks at the eight neighboring points to determine if the center point is an edge.\n\nMany image operations can be done by looking at a small window of pixels around each pixel. Each output pixel is created through some math done on that small window of input pixels. This is called convolution. It can be tricky to understand. The Mœbius shader article has an interactive Sobel demo, and I found a similar interactive sharpening demo. If you know of something better, please let me know!\nThe Sobel operator isn’t perfect, but it’s easy to implement in a fragment shader. If the Sobel operator’s calculated value is higher than some threshold, I count it as an edge and color the pixel black.
\n![\"Black](\"https://www.atomwolf.org/img/luma-edges-zDqBpKKN32-256w.webp\")
\n Edges detected from the grayscale version of the rendered scene's colors
\nIt does an okay job—better than I was expecting! Much of the interior geometry is lost, but the silhouette and some details are outlined.
\nThe next aspect used to add edges is depth. The depth map is a grayscale image where the color represents the distance from the viewpoint to the object.
\n![\"A](\"https://www.atomwolf.org/img/depth-RQlQK_DxS7-256w.webp\")
\n The depth map, where the pixel brightness represents how far away the point is from the viewpoint
\nOnce again, the Sobel operator detects edges.
\n![\"Black](\"https://www.atomwolf.org/img/depth-edges-pJwgsbI6Nu-256w.webp\")
\n Edges detected from the depth map
\nUsing the Sobel operator to detect edges using the depth map reveals edges around the window, the cutouts, and the silhouette. Most other edges are missed.
\nThe next aspect used to detect edges is the normal map. The normal of a surface is the direction the surface faces, and a normal map is an image that colors each surface based on the direction the surface faces.
\n![\"A](\"https://www.atomwolf.org/img/normal-XxiOaiyi8Y-256w.webp\")
\n The normal map, where colors represent the direction the surface faces
\nUsing the Sobel operator, again, we highlight detected edges in the normal map.
\n![\"Black](\"https://www.atomwolf.org/img/normal-edges-p5B4nUvZ_w-256w.webp\")
\n Edges detected from the normal map
\nWow! For this model, at least, the detected edges create a detailed outline. Parallel surfaces without intermediate geometry seem to be the cause of most missing edges.\n\nThere is at least one clever improvement to this method documented in the resources.\nFor example, when looking at the top from an angle, the far edges of the buttons usually aren’t outlined.
\nNext, I combine all the detected edges.
\n![\"Black](\"https://www.atomwolf.org/img/combined-edges-lO_KaEUnMA-256w.webp\")
\n Edges detected from the grayscale version of the scene's colors, the normal map, or the depth map
\nThis looks pretty good!
\nLet’s overlay the edges on the rendered scene.
\n![\"A](\"https://www.atomwolf.org/img/combined-cS4CwFZQ-Z-256w.webp\")
\n Detected edges overlaid upon the original rendered scene
\nLooking critically, the A and B labels are missing outlines from most viewpoints. Other edges are missing, and there are often so many outlines drawn on the standoffs that it looks like shading. There’s an issue with aliasing.
\nIt isn’t perfect, but this looks even better than I had hoped!
\nWhile working on this article, I made a tool to take screenshots of the shader in various configurations. I kajiggered it into an interactive demo where you can play with the shader settings. As I was brainstorming ways to present an explanation, I made another demo that shows all the views of the model in synchrony.
\nAssuming this works as well on other models, it’s good enough for me to consider outlines handled. In case I change my mind (or for the inevitable tinkering), I’ve collected some articles that detail improvements and alternate approaches.
\nI haven’t yet reviewed the shader with care. I built this shader through experimentation and chose the various settings haphazardly. I’m certain there are real improvements to be made and bugs to fix, even before improving the actual algorithm.
\nThe next step is to wrap this outline effect into a Web Component that integrates with model-viewer-effects. No one should have to write JavaScript to add this effect. It’ll go inside <model-viewer> tags like the built-in effects.
Additionally, I want to create a one-page “quick and dirty” example for using a custom shader with model-viewer, and an example model-viewer-effect-alike Web Component. I don’t think custom shaders for model-viewer are commonly asked about, but I want to help document them.
\nAfter exploring options for showcasing 3D CAD models on the web and compiling a list of desired features, I’m ready to experiment with Google’s model-viewer, using a real model I’ve been working on.
\nI’m making a small case for a T-Display S3 with a few buttons, a cutout for the screen and the USB-C port, a small prototyping PCB, and two Molex SL connectors. I exported some images from the modeling view in Fusion 360.\n\nFusion 360, a closed-source CAD suite, is my go-to for engineering 3D models. Although Autodesk recently added some features I've been wanting for years, like Configurations, I worry about its future. Wikipedia informs me it's been recently rebranded as just \"Fusion\".\n
\n![\"A](\"https://www.atomwolf.org/img/Case-(T-Display-S3)-v7-full-fUThdBuhnG-256w.jpeg\")
Showing all the components in Fusion 360’s modeling view
\nTo show the case details, I hid the electronics and the connectors.
\n![\"A](\"https://www.atomwolf.org/img/Case-(T-Display-S3)-v7-plastics-only-KBDJYaqVnx-256w.jpeg\")
Showing only the printed components in Fusion 360’s modeling view
\nmodel-viewer requires models in glTF format (or GLB, glTF’s binary equivalent). Fusion 360 doesn’t export to these formats without a plugin.\n\nI found two proprietary glTF exporters, one by ProtoTech Solutions and another by SimLab, but I want to avoid a closed-source plugin.\nBased on the model-viewer FAQ’s recommendation, I decided to try Blender as a converter.\n\nI like Blender. Blender is open source, and it's used by professionals and hobbyists. I haven't spent more than an hour or two with it. though, which isn't even enough time to make a good donut.\n
\nI exported the model from Fusion 360 in both FBX and USDz formats for comparison.
\nFBX is a proprietary file format controlled by Autodesk.
\nWhen importing the FBX into Blender using defaults, the model was oddly oriented.
\n![\"A](\"https://www.atomwolf.org/img/blender-fbx-import-6PsqPryEeX-256w.jpeg\")
FBX model imported into Blender
\nAfter some tinkering, I found that setting the import options for Manual Orientation to “Y Forward” and “Z Up” in Blender’s FBX import dialog resolved the orientation issues. Exporting to glTF 2.0 with the “+Y Up” option checked produced a correctly oriented model in model-viewer.
\nTo check scaling, I used the validation report in model-viewer’s editor. The model dimensions matched the dimensions in Fusion 360.
\n![\"A](\"https://www.atomwolf.org/img/fbx-editor-uCOv9ztGzy-256w.jpeg\")
Fusion 360 to FBX to glTF 2.0 via Blender, viewed in model-viewer’s editor
\nWith the Manual Orientation adjustment on importing FBX and the +Y Up option set when exporting to glTF 2.0, the glTF file has the correct orientation and scale.
\nUSDz is an open-source format developed by Pixar, with wide support in Apple products. It’s part of Universal Scene Description (USD).
\nImporting the USDz file into Blender maintained the correct orientation, but I encountered scaling issues. Setting the import scale to 0.001 in Blender’s import dialog resolved this problem.
\n![\"A](\"https://www.atomwolf.org/img/usdz-editor-iszvoR9bWQ-256w.jpeg\")
Fusion 360 to USDz to glTF 2.0 via Blender, viewed in model-viewer’s editor
\nWith the scale adjustment on importing USDz and the +Y Up option set when exporting to glTF 2.0, the glTF file has the correct orientation and scale.
\nWith the model successfully imported into model-viewer, I quickly realized that, compared to Fusion 360’s modeling view, it was difficult to see details in the model in model-viewer.
\n![\"A](\"https://www.atomwolf.org/img/neutral-env-JcfXwP-ILc-256w.jpeg\")
model-viewer rendering with “neutral” lighting environment
\nmodel-viewer lets you control the lighting and environment around the model. The previous image showed the model using the default scene with even lighting on all sides.
\nmodel-viewer also has a “legacy” environment meant for frontward viewing.
\n![\"A](\"https://www.atomwolf.org/img/legacy-env-2qAhWZq-DJ-256w.jpeg\")
model-viewer rendering with “legacy” lighting environment
\nThe “legacy” environment reveals more details than the “neutral” environment. Neither option came close to the clarity of Fusion 360’s modeling view with its outline rendering.
\nThis isn’t a case of model-viewer or glTF being “bad”. model-viewer does a great job rendering glTF.
\n![\"model-viewer](\"https://www.atomwolf.org/img/damaged-helmet-GcL8iIsTrV-256w.jpeg\")
model-viewer rendering a damaged helmet, one of the example models in model-viewer’s editor
\nglTF aims for photorealistic results through “physically based rendering”.\n\nglTF's physically based rendering (PBR) uses \"Bidirectional Scattering Distribution Functions\" and microfacets to model light interactions with surfaces. glTF includes a consistent set of parameters, helping to standardize PBR across various rendering engines. The Khronos Group, the consortium behind glTF, has a detailed explanation of PBR in glTF.\n
\nGood results from physically based rendering need good parameters and textures for the materials. In Fusion 360, I don’t usually do much with materials, textures, or colors. For this model, I set the material to “Plastic” and set the colors to some defaults. The materials were exported through an intermediate format into glTF 2.0.\n\nMaterials in physically based rendering have a base color and some surface parameters, but the rendered color of the surface may be quite different from the base color. Just like in the real world, the color of the light that bounces off a material isn't just the color of the material. It's influenced by the surface details and what the light was like before it interacted with the material. There are interactive lighting and color examples in the Lighting & Skybox model-viewer examples section. model-viewer's \"neutral\" lighting environment was engineered to color materials closely to the material's base colors. For more, read \"Achieving Color-Accurate Presentation with glTF\" and \"Tone Mapping Considerations for Physically-Based Rendering\".\nEven if I do well with the materials (and lighting), though, I should expect the render to show detail like a photo. I think the Fusion 360 modeling view does better than a photo.
\nCan I turn on outlines like in Fusion 360’s modeling view? model-viewer supports model-viewer-effects, an extension that changes the visuals. model-viewer-effect has an outline effect, but it only adds an outer outline around objects, not internal edges.
\nDon’t lose hope! All of this is open source. model-viewer-effects uses postprocessing, a library that makes effects using vertex and fragment shaders. If I can’t use postprocessing, I could plumb through model-viewer into three.js.
\nCan I add outlines to model-viewer?\n\n\"The Programmers’ Credo: we do these things not because they are easy, but because we thought they were going to be easy\", pinboard\nI have no experience with WebGL, three.js, or postprocessing. I am not sure what a shader is. Let’s find out!
\n\n\nEsperanto words are often made of roots extended with affixes and an ending. For instance, arbo, “tree”, is the root arb with the –o ending for nouns. –ar– is an affix meaning “group or collection of a bunch of things of the same type”. We can smush arb–ar–o together to get arbaro, which means “forest”. Similarly, amiko means “friend”, and amikaro is a “circle of friends”.
\nThere are lots of normal affixes, like –ejo for “place characterized by”, –end– for “mandatory” or “needs to be”, –ul– for “person characterized by”, or re– for “again”—but there’s also –um–.
\nEsperanto has a suffix, –um–, that doesn’t have its own meaning. It’s used to create another almost-root word related to the base word. An example may be helpful. Brako means “arm”. One of the most common –um– constructions is brakumi, which means “to hug”. There are some exceptions, like number bases and clothing named after body parts, but generally, you can’t break down an –um– word to figure out what it means. Without knowing exactly what brakumi means, the closest you could decipher from its parts would be “to do the arm thing”.\n\nWhen you break down the Esperanto word for \"to hug\", you get \"to do the arm thing\"? Oh, for cute!\n
\nI was listening to Apollo 18 in preparation for an upcoming They Might Be Giants show. One of the tracks, Dinner Bell, includes the following lyrics:
\n\n\n\n\n\n\nDinner bell, dinner bell, do the bell thing
\n
\nI’m waiting for the dinner bell to do the bell thing
\nDinner bell, dinner bell, ding ding ding
“Do the bell thing”? This is my chance! I’m going to combine They Might Be Giants and Esperanto, and finally show everyone how cool I really am!
\nAhem.
\nIf this were something formal, I wouldn’t translate “do the bell thing” with –um–. Folks wouldn’t know what you meant. However, translating a They Might Be Giants track? You better believe I’m gonna be singing sonorilumu!\n\nFor more on –um–, see Adventures in Esperanto's \"To word-thingy.\n
\nIf I were to write an Esperanto blog, I would hope it would be like Adventures in Esperanto.
\nThe author, Andy, has been writing about Esperanto since at least 2011. The posts are playful and are usually inspired by or citing passages from Plena Manlibro de Esperanta Gramatiko (PMEG). Plena Manlibro de Esperanta Gramatiko is an authoritative guide to Esperanto grammar, written for ordinary Esperanto speakers. I’ve been studying Esperanto for a while, but I am not an expert, so I really appreciate links to authoritative sources.
\nSome of the posts would likely be of interest only to folks who speak Esperanto (or are Esperanto-curious), but others should interest anyone who likes to play with language.
\nA few examples:
\nIn “Funniest joke on the internet”, Andy is inspired by an image in /r/linguisticshumor to translate
\n\n\n\n\n\"I am the ghost of Christmas Future Imperfect Conditional, said the spirit…
\nI bring news of what would have been going to happen, if you were not to have been going to change your ways.\"
\n
into Esperanto. I won’t spoil it!
\nIn “Shortcut to Phrasal Freedom”, Andy reviews the PMEG section on making words out of phrases, working through examples like “the back-pocketed phone”.
\nIn “Laden with Apricots”, Andy remembers a bottle of Glenmorangie Grand Vintage Malt 1991, and translates the description of its flavor notes.
\nZe Frank released a video a day for a year from March 2006 to March 2007.\n\nThis seems like ancient history to many, but "I was there, Gandalf. I was there three thousand years ago."\nIn retrospect, it may be difficult to see how much credit “the show with ze frank” deserves, because it was such an influence on the medium. Years after “the show” ended, he launched a new creative endeavour with the following video, “An Invocation for Beginnings”.
\nIt’s an incredibly inspiring call to action for “doing the thing”, making a creative mark. I’ve often returned to it.
\nIf I were to list my favorite lines from this video, I’d list the whole thing, albeit out of order, a line at a time. I’ll highlight just one:
\n\n\nThere is no need to sharpen my pencils anymore. My pencils are sharp enough. Even the dull ones will make a mark.
\n
If you liked this, you may like a piece I wrote with similar themes, “Preparing to Change”. It starts with They Might Be Giants lyrics and includes a different Ze Frank video.
\nI came across Vale, an open-source command-line tool that checks prose style. It’s like a linter or traditional style checker, but instead of code, it’s for text. I’ve been looking for something like this for a while!
\nVale understands a bunch of different files, like Markdown and HTML, and seems to be able to ignore markup pretty well.
\nOnce you’ve got it set up, there’s a few ways to integrate it into your work. You can put a Vale step in your review process or build pipeline. For folks on GitHub, there’s a Vale GitHub Action, and for other folks, it shouldn’t be tricky to integrate. (It exits non-zero when it finds issues, and it can print findings in multiple formats.) There’s also a Vale Language Server for editors that use Language Server Protocol things, and of course, you can run Vale on the command line.
\nI had some confusion and trouble setting it up. I had to review the entirety of the documentation a few times to get a general idea of how things go together.
\nI’m still no expert, but here’s how I set it up:
\n.vale.ini file in the root of the project. I started with the Config Generator. After reading the documentation and scratching my head, I ended up with something like: # See https://vale.sh/docs/topics/config/\n # and https://vale.sh/generator/\n .\n StylesPath = .vale\n \n # Hide some alerts based on severity. Set to suggestion, warning, or error.\n MinAlertLevel = suggestion\n \n # Make a directory at config/vocabularies/<thisvalue>/ in the StylesPath.\n # Vale will look there for an accept.txt and reject.txt, which should\n # consist of one word/phrase (or regular expression) per line.\n # The accept lines will be accepted, and the reject line will be rejected.\n #\n # See https://vale.sh/docs/topics/vocab/\n Vocab = atomwolf.org \n \n [*]\n BasedOnStyles = Vale.md in the content directory with vale content/**/*.md.atomwolf.org vocabulary file (.vale/config/vocabularies/atomwolf.org/accept.txt) for the words that Vale flagged that I wanted to keep. I put the words and phrases, one per line, in the accept.txt file. I didn’t have any phrases or words to always reject, so I didn’t make a reject.txt.Nunjucks is a template engine, “essentially a port of Jinja2”. Nunjucks uses brackets to delimit filters, comments, and other directives. Filters are surrounded by {{ and }}, comments are surrounded by {# and #}, and other directives are surrounded with {% and %}. One of Vale’s strengths is that it’s supposed to understand markup well enough to work around it, but Vale doesn’t understand Nunjucks yet.
\nWe can tell Vale to ignore these directives using the .vale.ini configuration file. I added:
\n [*.md]\n # Ignore Nunjucks directives, {{ foo }} {% foo %} or {# foo #}\n BlockIgnores = (?s){{.*?}}|{%.*?%}|{#.*?#}\n BlockIgnores tells Vale to ignore everything the regular expression matches—anything inside {% and }%, {{ and }}, and {# and #} in Markdown files. It’s pretty good, but it might not be perfect. If our directives add text to our output files, that text is going to bypass our Vale checks.
This site is made with Eleventy. Eleventy combines Markdown content files with templates and creates HTML files. If we want to be really pedantic, we need to check our HTML files, not just our Markdown input files, to check our prose after our templating and any other transformations.
\nYou can check Markdown files and HTML files at the same time, like vale content/**/*.md _site/**/*.html, but I prefer to check them separately. I check all the Markdown input files first, and only check and the HTML files if the Markdown files pass. If I misspell something in a Markdown file, it’s more helpful to flag that error and stop. Showing me the error in the HTML files dilutes the output. Because Vale exits non-zero when it finds problems, I can run Markdown checks first and HTML checks only if the Markdown checks pass with:
vale content/**/*.md && vale _site/**/*.htmlI have some files that I don’t want to check in content/articles/style/. (They’re used for automated testing.) I used find to give Vale the list of files I wanted it to check, and excluded the ones that should be skipped, with:
find content -type f -name \\*.md ! -path content/articles/style/\\* | xargs -0 valefind finds every file in the content directory that has a name that ends in .md and isn’t inside content/articles/style/. It gives those filenames to xargs, which uses those filenames as arguments and runs vale.
The built-in Vale style is pretty sparse—just spelling with that accepts.txt and rejects.txt. The Vale folks have created style packages for other style guides, like the Google Developer Documentation Style Guide and the Microsoft Writing Style Guide, and they’ve created packages that have the equivalent (or as close as you can get, I guess) of other prose style checkers and linters, like write-good and proselint. I found these at the “Vale Package Hub”.
After playing around with Vale, I made a sample .vale.ini config file that may be helpful.
\n # See https://vale.sh/docs/topics/config/\n # and https://vale.sh/generator/\n \n StylesPath = .vale\n \n # Hide some alerts based on severity. Set to suggestion, warning, or error.\n MinAlertLevel = suggestion\n \n # Make a directory at config/vocabularies/<thisvalue>/ in the StylesPath.\n # Vale will look there for an accept.txt and reject.txt, which should\n # consist of one word/phrase (or regular expression) per line.\n # The accept lines will be accepted, and the reject line will be rejected.\n #\n # See https://vale.sh/docs/topics/vocab/\n Vocab = atomwolf.org \n \n # Each package is grabbed from an online repository when you run\n # `vale sync` and placed into the StylesPath.\n #\n # See https://vale.sh/docs/topics/packages/\n # and https://vale.sh/hub/\n \n Packages = Google, write-good\n \n [*]\n # This configuration applies to all files.\n # Apply the rules from these styles\n BasedOnStyles = Vale, Google, write-good\n \n [*.md]\n # This configuration applies to all .md files.\n # Ignore Nunjucks directives, {{ foo }} {% foo %} or {# foo #}\n BlockIgnores = (?s){{.*?}}|{%.*?%}|{#.*?#}\n I looked through the Google and Microsoft style guides. I don’t want to use them as-is—this site has a different voice than the technical documentation they’re intended for.
\nI’d like to look through the style sets the Vale folks have made to mimic other tools, like proselint and write-good, and pull in the rules I like.
\nWhat I am really excited about, though, is making my own style guide, especially for different types of pages. In just a few minutes, I used Vale Studio to make a few helpful rules, like requiring particular headers in the dotted metadata block at the top of this page, and requiring that articles begin with an “Introduction” section.
\nI needed to create a bunch of identifiers that people were going to sometimes enter manually into a computer, or read to each other before entering them into a computer. For my situation, ideally, these identifiers would:
\n1 vs the letter i vs the letter l/ or \\, and don’t use characters reserved in URLs like + or ?j, 3, lowercase q, uppercase N”This group of goals isn’t unusual. I knew I wasn’t the first to have them. Sometimes, I want to dig right in and solve the problem. Sometimes, I want to skim the literature and grab a solution. Other times, I want to go deeper and understand the goals and constraints that drove the existing solutions. This can be really rewarding. Comparing goals, constraints, and approaches can reveal parts of your problem you didn’t know you had\n\nFor instance, some of these systems were designed to never produce particular words and others were designed not to make words at all. Upon reflection, I still don't think it's a goal here, but it's nice to have considered it.\n, but it often rewards in “non-productive” ways, too. It’s fun, and you’ll never run out of things to talk about at parties.
\nWikipedia has a decent collection of ways to encode binary data into text. Some of them overlap with our goals. For instance, some encodings explicitly cite ambiguous characters when explaining how the alphabet was chosen. The alphabet, or set of symbols used in an encoding system, is sometimes called the “dictionary” or the “character set”. Some try to handle character ambiguity by skipping characters that are easily confusable. Others specify a canonical encoding character for each group of confusable characters, and specify that all characters in the group decode to the same value.
\nThere are many encoding systems. I collected my notes on some and have summarized them below.
\nThese ideas have been around for a long time and have spawned many variants. Terminology tends to be a little sloppy, unfortunately. For instance, the term “Base64” is often used to refer to any number of encodings that use 64 printable characters, and the phrase “base 64” is used to refer to a particular encoding called Base64.
\nRFC 4648 specifies how to encode input into Base32, specifying not just “base”, but also padding, alignment, the characters with their values, and other details. You could come up with an alternate alphabet, for instance, and while it would use base 32, it wouldn’t be “base32”. “Decimal” and “hexadecimal” don’t quite belong in the same category as “Base64” and “Crockford’s Base32”. (Note: RFC 4648 also defines “base16” and it’s what you’d expect—0–9, A–F.)
My default option for encoding numbers for people is decimal. Decimal numerals (or decimals) are quick to say, easy to type, allowed in URLs and file paths, and already invented. They’re a good baseline.
\nNotably, using decimals doesn’t even require knowledge of the English alphabet.
\nDecimals aren’t dense compared to other choices. With only ten options per character, four digits in base 10 get us from 0 to 9,999, covering 10,000 values.
\nExamples of decimal identifiers include 42, 100, and 01189998819991197253.
Another option is hexadecimal, or base 16. Hexadecimal usually uses A–F as the digits beyond 0–9. These characters are unambiguous, easy to type, and are allowed in URLs and file paths.
Hexadecimal doesn’t require mixed-case characters, so no one needs to signify cases like “uppercase A, 7, lowercase b”.
With decimal, there are ways to read larger numbers, like “one thousand, three hundred and thirty-seven.” So far, none of the proposals for pronouncing hexadecimals have caught on (1, 2), so we’re limited to reading the characters one at a time.\n\nIn the show \"Silicon Valley\", Erlich Bachman says \"Ask me what nine times F is. It’s fleventy-five.\" Nine times 0xF is 0x87. It doesn't make obvious sense to me that you'd pronounce 0x87 as fleventy-five (unlike, say, maybe 0xF5). This might be a joke playing on Erlich's abilities; it may just be a mistake—either way, it's funny how long I spent thinking about it.\n
Sometimes, to distinguish hexadecimal from decimal or other bases, hexadecimal is written with a leading 0x, like 0x61 or 0x4D2. There are other programming notations, like an h suffix or a $ prefix, and in math, you may see a subscript after parenthesis, like (1012)16, but none of these would be necessary for these identifiers.
Many English words can be made with the traditional hexadecimal alphabet,\n\nLots of folks know about the BAD D00Ds and BABEs at the CAFE, drinking C0FFEE (even DECAF!). The café serves F00D, too, like BEEF, but few people know that the café has great F0CACC1A and FA1AFE1.\nespecially when you allow for letter substitutions, like 0 for O.
With 16 options per character, hexadecimal is denser than decimal. Four hexadecimal characters cover 65,536 values, from 0x0000 to 0xFFFF.
Examples of hexadecimal identifiers include 35, 4D2, and BADDECAFC0FFEE.
Base64 is commonly used to transmit binary data via ASCII. To get 64 easily typed symbols, we have to use at least some letters in both upper- and lowercase, which makes it more awkward to read out than previous options.
\n\nThere are many variations in what folks call “Base64”, but the “standard” “Base64” is defined in RFC 4648. The normal alphabet has / in it, which can be a pain in URLs and filenames.
Base64url, an alternate standard also proposed in RFC 4648, becomes file- and URL-safe by replacing + and / with - and _. It still has upper- and lowercase letters. Eliminating + and / make it easier to use in URLs and file systems, but distinguishing - and _ may be problematic! (There are other standard alphabets, too.)
Base64 is quite dense. Four characters of Base64 cover 16,777,216 values, from AAAA to ////.
Examples of Base64 include NDI=, MTAw, and MTIzNA==.
Base32 seems to be closer to our needs. It uses 32 symbols. There are a few standard dictionaries, and nothing, really, stopping you from creating your own. Base32 variant dictionaries often only contain one letter case, omit /, and some skip easily confused pairs, like 1 and lowercase l. The “standard” Base32 definition is in RFC 4648. The alphabet contains A–Z, 2–7, skipping 0 and 1.
The RFC also defines “base32hex” with an alphabet of 0–9, A–V. Base32hex has all the numerals in it, and, unlike Base32, when compared bit-wise, the encoded data sorts the same as the decoded data.
With 32 options per character, a four-character Base32 string covers 1,048,576 values.
\nExamples of Base32 identifiers include 2C45, 42, and WORD.
“Crockford’s Base32” excludes I, L, and O for ambiguity, and U for “accidental obscenity”. It also distinguishes decode symbols from encode symbols, allowing someone to enter a 1, i, I, L, or l, and they all mean the same thing—but it will re-encode that symbol to a 1. Crockford’s Base32 also allows for an optional checksum, which requires an extra five symbols, *, ~, $, =, and U.
Like the other Base32 variants here, with 32 options per character, a four-character Crockford’s Base32 string covers 1,048,576 values.
\nExamples of Crockford’s Base32 identifiers include 6GS0 and 64SK6DR.
Base32H is a newer proposal, similar to Crockford’s Base32 in a lot of ways. Base32H was designed assuming it’s always encoded into numerals and uppercase letters. Due to the uppercase assumption, while I and 1 are aliased together, L isn’t included. It also aliases U with V, 1 with I, and 0 with O. It doesn’t have a built-in mechanism for checksums. The canonical uppercase encoding may make it awkward in some places, like URLs.
Like the other Base32 variants here, with 32 options per character, a four-character Base32H string covers 1,048,576 values.
\n\nExamples of Base32H include 1A and 19R, but any string of 0–9 and A–Z (and a–z) can be decoded using Base32H.
Google created the “Open Location Code” (also known as Plus Code) geocode\n\nI could get lost reading about geocodes; they're so interesting! See also \"discrete global grid\".\nas an alternative to latitude and longitude coordinates.
\nOpen Location Codes use a base 20 encoding. They use 2 through 9, C, F, G, H, J, M, P, Q, R, V, W, and X. Doug Rinckes on Google’s Travel team says:
\n\n\n[…] the character set was chosen to avoid spelling words in more than 30 different languages. We removed similar looking characters to reduce confusion and errors, and because they aren’t case-sensitive, they can be easily exchanged over the phone.
\n
Avoiding spelling words across many languages wasn’t one of my goals, but it was interesting enough to include in this round-up!
\nOpen Location Codes are more complicated than just using that alphabet as a base 20 encoding, but an example Open Location Code is 86P8XPC6+39.
With 20 options per character, four digits in base 20 cover 160,000 values.
\nExamples of base 20 identifiers using this character set include 555, X0X0, and MP303.
If you take the characters from Open Location Code from before, and use both uppercase and lowercase versions of the letters, you get 32 characters. This has been called a “word-safe” Base32.
\nThis is mixed-case, of course, but the amount it tries to avoid words seems impressive.
\nLike the other Base32 variants here, with 32 options per character, a four-character “word-safe” Base32 string covers 1,048,576 values.
\nExamples of “word-safe” Base32 identifiers include 23 and j37xPX.
| System | \n0/Oo | \n1/Ii | \n1/Ll | \nIi/Ll | \n8/Bb | \nUu/Vv | \n5/Ss | \n
|---|---|---|---|---|---|---|---|
| Decimal | \n\n | \n | \n | \n | \n | \n | \n |
| Hexadecimal | \n\n | \n | \n | \n | ❌ | \n\n | \n |
| Base64 | \n❌ | \n❌ | \n❌ | \n❌ | \n❌ | \n❌ | \n❌ | \n
| base64url | \n❌ | \n❌ | \n❌ | \n❌ | \n❌ | \n❌ | \n❌ | \n
| Open Location Code Base 20 | \n\n | \n | \n | \n | \n | \n | \n |
| RFC 4648 Base32 | \n\n | \n | \n | \n | \n | ❌ | \n❌ | \n
| Crockford’s Base32 | \n\n | \n | \n | \n | ❌ | \n\n | ❌ | \n
| Base32H | \n\n | \n | ❌ | \n\n | ❌ | \n\n | \n |
| “Word-safe” Base32 | \n\n | \n | \n | \n | \n | \n | \n |
Each column represents a character pairing, like 0 and O/o, and each row represents a particular system. If a cell contains ❌, that row’s system distinguishes between characters in the first group from characters in the second group. A row with many ❌s is more likely to generate confusing outputs (depending upon context like how the output is presented, the font face, the size, and how the media wears over time).
| System | \n\n |
|---|---|
| Decimal | \n0 1 2 4 5 6 7 8 9 | \n
| Hexadecimal | \n0 1 2 4 5 6 7 8 9 A B C D E F | \n
| RFC 4648 Base64 | \n0 1 2 4 5 6 7 8 9 A a B b C c D d E e F f G g H h I i J j K k L l M m N n O o P p Q q R r S s T t U u V v W w X x Y y Z z + / (=) | \n
| Base64url | \n0 1 2 4 5 6 7 8 9 A a B b C c D d E e F f G g H h I i J j K k L l M m N n O o P p Q q R r S s T t U u V v W w X x Y y Z z - _ (=) | \n
| RFC 4648 Base32 | \n2 4 5 6 7 A B C D E F G H J K M N P Q R S T V W X Y Z (=) | \n
| Base32hex | \n0 1 2 4 5 6 7 8 9 A B C D E F G H J K L M N P Q R T V (=) | \n
| Crockford’s Base32 | \n0 1 2 4 5 6 7 8 9 A B C D E F G H J K M N P Q R S T V W X Y Z (* ~ $ = U) | \n
| Base32H | \n0 1 2 4 5 6 7 8 9 A B C D E F G H J K L M N P Q R T V W X Y Z | \n
| Open Location Code Base 20 | \n2 4 5 6 7 8 9 C F G H J M P Q R V W X | \n
| “Word-safe” Base32 | \n2 4 5 6 7 8 9 C c F f G g H h J j M m P p Q q R r V v W w X x | \n
Remember:
\nBoth Crockford’s Base32 and Base32H satisfy my original goals reasonably well, but I’m slightly partial to Crockford’s Base32.
\nBase32H has a lot of features that seem nice—like “every string of alphanumerics is a valid input”—but I’m not sure that I’ve needed them. In general, I like the alphabet used in Crockford’s Base32 a little better than Base32H’s. Compared to Crockford’s Base32, Base32H drops S (to reduce confusion with 5) and allows both L and 1, arguing that by telling folks to always output capital letters, there’s no ambiguity between L and 1.
Ultimately, breaking down this problem into goals and constraints and comparing existing solutions through that lens proved enlightening.
\nMy hopes and dreams for a 3D CAD model viewer may be nitpicky and particular, but they’re mine. I’m planning to write about CAD models, and I want to point to details in an interactive web viewer. I started a list of goals when I decided to begin with model-viewer, and I’ve added to it.
\nannotations (hotspots)
\nI need to be able to add a caption to a model feature and to move the camera to show a specific view of an annotation.
\ncomponent visibility
\nI need to be able to hide or show specific components of a model. For instance, I need to be able to show and hide the lid of a box.
\nshow dimensions
\nI need to be able to add the overall dimensions of a model.
\nbanana for scale
\nThis is silly, but I’d really like the ability to add a banana next to a model.\n\nPer Know Your Meme, the earliest instance of a person posting a photo online with a banana for scale was in 2005 on the blog Rock Dog Designs. Using the Wayback Machine, I found the original post. \"I don’t know how big the screen is, we’re moving and I can’t find the tape measurer. But I do have a banana. For scale. Oh wait, my husband says it’s 19inches [sic]. Oh well, I’ll leave the banana for interest. Please be interested.\"\nOther folks have made an STL viewer with a banana for scale, and you can add a banana for scale in KiCad.
\nAugmented Reality (AR) / Virtual Reality (VR)
\nIt’d be nice if it were easy to use a mobile device to see what a model looks like on a desk or in a visitor’s particular environment, and it’d be nice if it were easy to use a VR headset to interact with the model.
\nrendering the models I want to use well
\nThere’s a lot I don’t know about 3D rendering, and a viewer that does great rendering shoes or models from video games might not automatically do well rendering the CAD models I want to show.
\nopen source
\nI wrote more about why I want to use an open-source viewer in “Choosing a 3D CAD viewer”, but one reason is that I need to be able to modify the viewer.
\nnot reliant on centralized service or hosting
\nI want to be able to host my own models and the viewer itself. If the viewer changes, I don’t want to be forced to quickly update my site. I wrote more about this in “Choosing a 3D CAD viewer”.
\nquick to load
\nAdding the viewer to a page shouldn’t make the page slower in a way that people can tell. Real-world web performance is more complicated than Lighthouse scores, but the viewer should still allow perfect Lighthouse scores on mobile and desktop.
\nlow page weight (data)
\nIf a visitor doesn’t interact with the viewer, the browser shouldn’t need to download much extra data.
\naccessibility
\nThis isn’t a complete list, but it should work well for folks without JavaScript, with vision impairments or with a screen reader, with older browsers, with slower connections, with limited or metered data, and even to folks who like printing things.
\nsupport progressive enhancement
\nAdding a 3D viewer to a page shouldn’t break the page for folks who can’t use the viewer. One option has the an image with good alt text and a caption, and the interactive viewer seamlessly replaces the image. If the viewer doesn’t load, the visitor still gets the image.
\nNext, I’m going to load an example CAD model into model-viewer and see how it fares.
\nWe’ve been putting 3D models on the web since 1994, but doing it well is tricky. The more I learn, the more complicated it seems.\n\nmitxela built their own viewer and wrote a good writeup. Among other things, it reveals a glimpse of the complexity of camera control.\nI want to write articles showcasing CAD models in an interactive web viewer. I looked toward existing options for inspiration.
\nThe first 3D viewer I found was Sketchfab. Sketchfab says it’s the “best 3D viewer on the web”. I don’t know about that, but I do like the annotations.
\n![\"A](\"https://www.atomwolf.org/img/sketchfab-annotation-i6h7zmiuoB-256w.jpeg\")
A model annotation from the Sketchfab Annotation Demo
\nIf I were to use Sketchfab, Sketchfab would host my 3D models. I’d add an iframe with a particular Sketchfab URL to a page, and web browsers would create a page-within-a-page to show the viewer. Sketchfab has a JavaScript API that lets developers interact with the viewer in the iframe to develop some custom features.
Sketchfab’s viewer is hosted by Sketchfab, and my site would just refer to it. If Sketchfab changed their viewer, the viewers on my pages would change, whether I wanted it or not. If Sketchfab had an outage, my pages would be broken. If Sketchfab went out of business, I’d have to scramble to replace them. If the Sketchfab viewer were open source or if I could host it, I’d be less concerned.\n\nI've found that relying on this type of service tends to create emergencies for me. The more services like this I use, the more frequently my work is driven by upstream changes. Having something I host, something I update, helps reduce those emergencies. Being able to use a previous version is really helpful!\nFurthermore, my ability to modify the viewer is limited.
\nFor the features I’d like, Sketchfab seems expensive. I think Sketchfab would cost me at least $129 per month.
\nI don’t think Sketchfab is a good fit for a 3D viewer for ATOM
Autodesk has a web viewer. I can save my Fusion 360 projects to their storage and look at them in the browser. The viewer displays the model to look just like it does in Fusion 360. You can rotate and zoom, measure parts of the model, run saved animations, and show and hide parts of the model. I can make the project public and embed the viewer into a page.
\nThe Autodesk viewer wouldn’t cost me anything extra, but my other concerns about Sketchfab apply here.
\nAfter Sketchfab and the Autodesk viewer, I had a better sense of what I wanted.
\nI don’t want to use a viewer that’s an iframe to an external site or one that only shows models hosted at an external site. I want to be able to host the models and the viewer.
I want to be able to modify the viewer. It should be open source.
\nI need to add text to call out model features to discuss design decisions. These are called “annotations” or “hotspots”.
\nAfter surveying more viewer options, I grouped them into categories.
\nFramework viewers are more like libraries or examples than applications. They handle many complexities but would require development work to integrate into a site.
\nThree.js is an open-source JavaScript library for 3D graphics in the browser. It uses WebGL, and it can use WebXR to do Virtual Reality (VR) things. It has good docs, a bunch of examples, and it’s been around since 2010. It’s pretty awesome. Most of the other options on this page are either built on three.js or built on things built on three.js.
\nI’m not sure three.js has a viewer. They have an editor and many loader examples. I’d definitely have to build a lot of the features I want.
\nA-Frame is a fun web framework built on top of three.js, meant for VR. My first VR development experience used A-Frame. I made a demo that played videos and used a controller for 3D space data logging. After getting through some conceptual hoops around VR development, using A-Frame was really quick. I liked it, but I don’t think I’d use A-Frame for this project.
\nBabylon.js’s viewer (example)
\nBabylon.js is similar to three.js, but the library is a bit less graphics-y and a little more “game engine-y”. The Babylon.js model viewer has a lot of features: animations, asynchronous loading of models, the Babylon.js Inspector. I didn’t see annotations, and the interface would need to be modified.
\nThese viewers are meant to be used as-is. They vary widely, and I gave some only a glance.
\nDon McCurdy’s three-gltf-viewer (GitHub)
\nThis viewer is built on three.js. It supports animations but doesn’t appear to support annotations or VR/AR/WebXR.
\nkovacsv’s Online3DViewer (GitHub)
\nI don’t know a lot about kovacsv’s Online3DViewer. It’s open source and uses three.js. The viewer is embedded using an iframe. I don’t think it has annotations or VR/AR/WebXR support.
\nView3D (GitHub)
\nView3D is built on three.js. It’s open source. It supports annotations and animations. It supports augmented reality through WebXR, Android’s Scene Viewer, and iOS’s AR Quick Look. It appears to be maintained by a South Korean company called Naver.
ThreePipe is built on three.js. ThreePipe says it has a “simple, intuitive API for creating 3D model viewers/configurators/editors on web pages, with many built-in presets for common workflows and use-cases.” It has plugins, including one for Gaussian splats.\n\nGaussian splats don't seem helpful for this project, but they're interesting!\nIt doesn’t appear to support WebXR/AR/VR yet, and it doesn’t appear to support annotations.
\nmodel-viewer is a Google project. It’s open source and built on three.js. It’s got a lot of examples. It supports annotations, and AR through WebXR, AR Quick Look, and Scene Viewer. VR support seems to be in progress. It has an example showing model dimensions. There is good integration between the 3D viewer and the rest of the webpage. It feels “in the spirit of the web”.
\nmodel-viewer has a lot of polish. It can show an “interaction prompt” animation on the model, giving visitors an affordance that the model isn’t a static image. model-viewer has an editor to help with configuration. The model-viewer folks care about and track [page load performance].(https://modelviewer.dev/examples/lighthouse.html)\n\nAsynchronously loading model-viewer decreases its impact on page load performance, but model-viewer is still 60+ KB. Lite model-viewer is an easy-to-use third-party wrapper that defaults to only loading model-viewer after the visitor interacts with the model image. For a visitor that isn't going to interact with the model, using lite-model-viewer means the page size is only around 3 KB larger than just showing the image!\nmodel-viewer starts with a pre-rendered image of the scene and seamlessly replaces it with the interactive model when the model file loads. This is “in the spirit of the web” and heavily influenced my decision to start with model-viewer.
\nAnother way model-viewer aligns with the web is that it’s a Web Component. You don’t need to write JavaScript to put a model on your page. You can add a <model-viewer> tag. Awesome!
model-viewer is open to modifications. model-viewer-effects provides postprocessing effects, like pixelation, glitching, and antialiasing. Additionally, I could hook into three.js and modify things how I like.
\nI’m going to start with model-viewer, but not without reservation.
\nmodel-viewer is maintained by folks from Google. While I’m cautious of Google’s history of discontinuing projects, the open-source nature of model-viewer gives me reassurance. When Google decides it’s done with model-viewer, the community might maintain it, but I could continue to use the last version while migrating to another option, like View3D or ThreePipe.
\nMy next step is to discover the rest of my finicky requirements as I integrate model-viewer into ATOM
I sometimes find myself in a particular situation with git. I have a small series of logical commits in a pull request. I need to make some edits.
\nI could always make the edits on top of the logical commits and push the new commits, but usually, I’d rather edit the logical commits.
\nMy usual workflow for something like this used to be:
\ngit commit --amend.git add -p and create a new commit only containing the edits for a single commit. Commit with git commit --fixup fa1afe1.\n\nYou don't have to use the short SHA-1. There are lots of ways to name a commit, like HEAD~3 or :/Add some bugs. :/<regex> returns the youngest matching commit. Some folks like it.\nWith --fixup, git sets the commit message for the new commit to something like fixup! fa1afe1: <original commit message>. Git will use the commit message later to be helpful.\n\nIf the original commit message needs to be changed, I'd probably commit with --squash and add a reminder in the new commit's commit message. The rebase step will change this commit's action to \"squash\" instead of \"fixup\". In an interactive rebase, \"squash\" opens an editor with the original commit message on top and the commit message for the to-be-squashed commit on the bottom, and has you edit the message before continuing with the rebase. (I see there's git commit --fixup:amend now, which looks to be another way to edit the commit message during the rebase.)\ngit add -p and committing until there are no more changes left.git rebase -i --autosquash main.\n\nI don't really put --autosquash in the command. I set rebase.autoSquash in my git config.\n. It opens up the editor just like git rebase -i. However, because of autosquash, those fixup! fa1afe1: commits we just made have their action set to “fixup” and they’re reordered to be right after the commits they refer to. I take a quick look, save, and exit. Git does the rebase, and my local branch is updated.git push --force, updating the remote branch.Autosquash is pretty helpful. When you rebase, those fixup and squash commits will be reordered and have the appropriate action based on the commit message.
\n\n\n\n
--autosquash
\n--no-autosquash
\nWhen the commit log message begins with “squash! …” or “fixup! …” or “amend! …”, and there is already a commit in the todo list that matches the same..., automatically modify the todo list ofrebase -i, so that the commit marked for squashing comes right after the commit to be modified, and change the action of the moved commit frompicktosquashorfixuporfixup -Crespectively. A commit matches the...if the commit subject matches, or if the...refers to the commit’s hash. As a fall-back, partial matches of the commit subject work, too. The recommended way to create fixup/amend/squash commits is by using the--fixup,--fixup=amend:or--fixup=reword:and--squashoptions respectively of git-commit.
As helpful as autosquash is, it’s relatively transparent. If you made a regular commit, then did an interactive rebase, reordered that regular commit to be underneath the one you wanted to fixup, and changed the action from “pick” to “fixup”, you end up at the same place. These special commands get you some automatic human-readable information in the temporary commit, and the rebase part reads that commit message to do a bit of text editing for you.
\nI didn’t terribly mind the workflow (git add -p, git commit --fixup, git add -p …, git rebase -i).\n\nI do find git add -p over and over to be tedious and have long wished for a way to do everything git add -p does, but with deleting/undoing changes and sorting things into multiple changesets in one go.\nI stumbled upon git absorb, though, and have found it even nicer.
Enter git absorb, a snazzy git plugin. After you install it:
\ngit add -p.git absorb. It checks if the hunks you’ve staged match or are inside hunks you changed in previous commits, and puts those into fixup commits, leaving anything that remains in the staging area.git rebase -i --autosquash main.If you don’t want to review the changes during the interactive rebase, you can git absorb --and-rebase.
I added a fun MakeCode Arcade demo Bouncing DVD Logo to Projects.
\n![\"A](\"https://www.atomwolf.org/img/static-dvd-logo-kD63Mx4L0C-256w.jpeg\"){kind=logo}
MakeCode Arcade can be a slick way to introduce folks to game development. You write and play games in a browser. The programs can be loaded onto little handheld devices like the Adafruit PyBadge.\n\nThe editor and handheld electronics aren't the only places you can run MakeCode Arcade games. Their kiosk provides a simple menu interface to select between games, perfect for something like an arcade machine.\n
\nI occasionally run MakeCode Arcade workshops for kids and teens at Leonardo’s Basement, and make little demos to show off a feature or a technique.
\nEven before I was finished, this demo put a big grin on my face.\n\nI was surprised the demo landed as well as it did with the students. They mentioned the episode of US version of The Office and this (edited, unfortunately) clip of a bar crowd cheering on the DVD logo.\n
\nRead more (and watch it, edit it, and make it your own!) at the Bouncing DVD Logo project page.
\nLogseq has relatively best-in-class PDF annotation support. My biggest problem was that all PDF citations\n\nI don't know that Logseq has a name for the annotation link. Here, I call it a \"citation\".\nonly show the page number of the reference. If you refer to multiple documents, you need to click through to tell which one refers to which document!
\n![\"Logseq](\"https://www.atomwolf.org/img/logseq-citations-before-vYOn0YKcnN-256w.jpeg\")
Each yellow circle indicates a PDF citation. The number is the page number of the PDF (a good start!) but which PDF?
\n![\"Logseq](\"https://www.atomwolf.org/img/logseq-citations-after-WCf4UnXjUm-256w.jpeg\")
With a handle like “HtN” and “GtN”, I can tell which citation refers to which document.
\nI posted in the Logseq Discord:
\n\n\nHiya folks! I’m looking to extend the (colored dot) P annotation handle thing. I really want to pull in a PDF name—maybe defined as a property on the annotation page? i.e. instead of * P240 “hello world” it may say something like * Logseq for dummies P240 “hello world”. Is this possible? Anyone have any tips or pointers? I am a pretty competent programmer but haven’t done Logseq plugin-y work before.
\n
Someone named Charlie jumped in, and said:
\n\n\nCool! That’s a great idea! The current plugin SDK doesn’t provide an API to intercept the rendering of PDF annotation blocks. Even if it is possible to achieve through hacking, it may be complicated and have performance issues. We will consider implementing this feature natively or providing a specific plugin API as soon as possible.
\n
Phrased like a seasoned open source developer!
\n\nUnfortunately, I have to quickly pick the underlying tool for an annotation project. There are no clear winners, but Logseq is at the top. This is one of the main blockers—if I can hack this feature in, even in a hard-to-maintain and performance-impacting way, it may be enough to make me feel comfortable using Logseq for the project. I hope by the time I’m done with the project, Logseq won’t have this problem anymore.
\nI haven’t worked with Logseq’s internals before, and I don’t think I’ve worked with Clojure. I’ve done some work in Lisp-y environments, though, so I opened up the source. Within a few minutes, I was able to find where the citations get added (in block.cljs). I could tell that the section didn’t directly have the document or document name, but it did have the document ID. Time for hacking!
I set up the development environment.
\nyarn, and then yarn watch.localhost:3001, but PDF stuff didn’t seem to load right. I had thought the PDF stuff worked on the web interface, actually, but I’m not sure if it does. Before digging into that, I decided to try the Electron app.yarn watch and waiting for it to get to a steady state, and then opening a new terminal and running yarn dev-electron-app. I kept both running. The PDF citation seemed to work like it did in my regular version of Logseq.(println \"hello world\") in the program, the output would show up in the browser JavaScript console.logseq directory with PyCharm and installed the Clojure plugin.This wasn’t done with any real knowledge of Clojure or Logseq internals, unfortunately, so please don’t take this as a great example of how to do Clojure work! I saw reference to a REPL, but the Electron change loop was pretty fast, and I wasn’t sure I had the Clojure knowledge to translate things from the REPL into a plugin or patch to the source.
\nWhile looking for examples of getting properties through a database lookup, I found some code in Logseq that was using debug/pprint. The advantage of using pprint over println appeared to be that pprint would indent the output to show the structure of the data better.
I incrementally found the reference to the PDF document, got a property of that page through a database lookup, and then rendered it in the citation.
\n\n\n \n \n (debug/pprint \"adamwolf: t\" t)\n (debug/pprint \"adamwolf: (:block/page t)\"\n (:block/page t))\n (debug/pprint \"adamwolf xyzzy: (db-utils/pull (:db/id (:block/page t)))\"\n (db-utils/pull (:db/id (:block/page t))))\n (debug/pprint \"adamwolf (db-utils/pull (:block/page t))\"\n (:hl-handle\n (:block/properties\n db-utils/pull\n (:db/id\n (:block/page t)))))I added some comments to explain my intent. \n\nYou can see the change in context.\n
\n\n\n \n \n ;; Get the ID of the page referred to by t's :block/page.\n ;;\n ;; Use that ID to pull the page from the database, and\n ;; only take the :block/properties map.\n ;;\n ;; Look up the :hl-handle in the :block/properties, and\n ;; bind it to awolf-hl-handle.\n ;;\n ;; If any of those things are nil or don't exist,\n ;; awolf-hl-handle is nil.\n ;;\n ;; Then, if awolf-hl-handle is not nil, render a\n ;; span.hl-handle with the handle and a space in it.\n \n (let [awolf-hl-handle\n (:hl-handle\n (:block/properties\n (db-utils/pull [:block/properties]\n (:db/id\n (:block/page t)))))]\n (when awolf-hl-handle\n [:span.hl-handle\n [:strong.forbid-edit (str awolf-hl-handle \" \")]]))Now, if I add a property of hl-handle:: foo to a document page, all the citations for that PDF are formatted like foo P103! Great!
This is definitely a good proof of concept. Is it something I would want to use locally for a bit?
\nSpeed and Scalability
\nI’ve added a database lookup for every block title render of a citation, I think, and I don’t think there were any database lookups before. I don’t know Logseq enough to know if this is something to worry about. Is there a cache I should be explicitly using? Should I pull in a copy of the handle into the highlight’s properties, and then updating all the highlights if the handle changes? Is the lookup actually fine? ¯\\_(ツ)_/¯ Rendering speed seems fine on my largest pages on my desktop—which, for a change intended for myself, seems like a reasonable test.
Database and Disk Format Agnosticism
\nI want to avoid affecting how things are stored in the database or on disk. Locking myself into a custom Logseq sounds like a bad idea!
\nI think the change only affects presentation.
\nMaintenance Effort
\nAs Logseq changes, is this patch something that I could easily bring forward without a lot of work?
\nThe change is short and doesn’t touch a lot of parts of Logseq. Maybe!
\nTo close the loop, I posted an update in the Discord. I wanted to make sure that if someone came across my request in the future, they wouldn’t find a “Oh yeah, I got it working!” message with no details. I also wanted to make sure I didn’t come across expecting my quick-and-dirty change to be adopted across the whole project.
\nI posted the following in the Discord thread.
\n\n\nOK, so for posterity’s sake, lemme post what I did. I added the following to
\n\n\n \n \nblock.cljs.\n;; Get the ID of the page referred to by t's :block/page.\n ;; Use that ID to pull the page from the database, and only\n ;; take the :block/properties map.\n ;; Then, look up the :hl-handle in the :block/properties,\n ;; and bind it to awolf-hl-handle..\n ;; If any of those things are nil or don't exist,\n ;; awolf-hl-handle is nil.\n \n ;; Then, if awolf-hl-handle is not nil, render a\n ;; span.hl-handle with the handle and a space in it.\n (let [awolf-hl-handle (:hl-handle (:block/properties (db-utils/pull [:block/properties] (:db/id (:block/page t)))))]\n \t(when awolf-hl-handle\n \t\t[:span.hl-handle\n \t\t\t[:strong.forbid-edit (str awolf-hl-handle \" \")]]\n \t\t)\n \t)This adds a db lookup for every single block render of an annotation, maybe for every block. The code is probably an abomination. I haven’t ever used Clojure before, and I don’t really know how Logseq works in any way. This is a little personal proof-of-concept patch.
\nAnyway, after that, you can add an
\nhl-handle:: fooproperty to the annotation page, and then those annotated things will show up with the handle prefix before the page number.
I hope developers add a PDF citation plugin hook. I’d like to see this feature without maintaining a fork (albeit a tiny one). I like the document handle, but there’s room for improvement. For instance, supporting custom citation formats! I’d like to see a chapter number, actually, even if only in exports.\n\nZotero, for instance, supports thousands of citation formats. There's even a Citation Style Language supported by multiple tools!\nGiving an export to someone without the PDF becomes more useful when a citation reads “Gideon the Ninth, ch. 32, p. 409” rather than “P409”.
\nI’m working on a commissioned art piece where we’re looking for thick, exaggerated 3D printer layer lines.
\nI bought a 1.2 mm high flow nozzle, much bigger than I’ve used before, and started tuning the settings. For a demo piece, I used a Benchy, scaled 2x. My first print with the nozzle was with a 0.9 mm layer height.
\n![\"A](\"https://www.atomwolf.org/img/chonky-benchy-1-qPIO2DbKDb-256w.jpeg\")
The chonky Benchy fills my hand, and feels quite solid.
\n![\"Another](\"https://www.atomwolf.org/img/chonky-benchy-2-VP8i_ZV3rm-256w.jpeg\")
It turned out great, considering it’s a first print with a new nozzle and a custom configuration.
\n![\"The](\"https://www.atomwolf.org/img/chonky-benchy-3-ELUBwS6E6D-256w.jpeg\")
“The chonky Benchy with a soda can for comparison”
\nI really like how it turned out! It’s heavy and feels really solid.
\nThe exaggerated layer lines remind me of early 3D printing experiments–but it looks so much nicer than my early 3D printing experiments did!
\nI recently designed a case and stand for the Adafruit ESP32-S3 Reverse TFT Feather. The case/stand is a single piece, and snaps onto the board. The feet hold the electronics off the table whether it’s on its back or on its side. The little fins prop the board up at an angle when it’s standing. The buttons on the front flex and do a decent job preserving the clicky feel of the buttons on the board.
\nI think it could use another revision with little retention nubs in the corners to hold the board in place better. I’ve noticed that if I push the buttons too hard without supporting the board, the board pops out.
\n![\"A](\"https://www.atomwolf.org/img/PXL_20230505_212716003.MP-z_cotE_XN7-256w.jpeg\")
3D printed case for the Adafruit ESP32-S3 Reverse TFT Feather in action
\n![\"A](\"https://www.atomwolf.org/img/PXL_20230505_212727584.MP-J5TAh9Da3Y-256w.jpeg\")
“Case” may be an overstatement. The whole thing clips on the front of the Feather.
\n![\"The](\"https://www.atomwolf.org/img/PXL_20230505_212804161.MP-hGryOJLwGx-256w.jpeg\")
This is the USB-C side.
\n![\"A](\"https://www.atomwolf.org/img/PXL_20230505_212817721.MP-id9zlkze04-256w.jpeg\")
The little stand fins means it can stand angled on its side.
\n![\"The](\"https://www.atomwolf.org/img/PXL_20230505_212833456.MP-uPwJh_bF2O-256w.jpeg\")
The back legs means it can lay down flat while staying off the table.
\nI frequently need to do simple parsing. Often I resort to grep and cut, or a regular expression I send through Python. I rarely use something like awk.
\nI needed to look for a pattern in some text coming through a pipeline (“Configuration backup archive complete”), split that line up by colons, and print the second field. This is what I came up with:
\n| awk -F: '/Configuration backup archive complete/{print $2}'
Sometimes, I want to watch for changes in a particular file on GitHub.
\nWhen I’m part of the development team, sometimes a CODEOWNERS file works. GitHub will automatically flag me on upcoming changes to particular files or directories.
\nIf I’m not a member of the repository, a CODEOWNERS file won’t work. I found out recently that GitHub has RSS/Atom feeds for the contents of repositories. To watch the file README.rst on the main branch of https://github.com/adafruit/circuitpython, use the RSS feed https://github.com/adafruit/circuitpython/commits/main/README.rst.atom.
\nThanks, Jake!
\nBeyond this, I would love to be able to watch for public pull requests that affect that file. Let me know if you have any ideas!
\n