the top README.md improvement

ytanimura commented 1 year ago

Discuss improvement of README in the top.

The draft will be used here, and I will list the points I was concerned about.

virtualritz commented 1 year ago

truck was posted on Hacker News today and there is some discussion about the README too.

ytanimura commented 1 year ago

A few thoughts. You can find it posted here. https://github.com/ricosjp/truck/blob/readme-renewal/README.md Since "virtualritz" disappeared from contributor in the previous revert, I should think of some way to deal with it.

I was very surprised at the revisions we received. As I think daily about how I felt when I created this product, the current state of truck, and its contribution to the business of our company, I was suddenly presented with a third-party view of what truck looks like. I would like to comment on each of the revisions we have received, considering the intent at the time of writing and the current status of each one.

The explanation of Principle is long, so I will first itemize the main points regarding the other points.

truck is a recursive abbreviation for "Truck is a RUst Cad Kernel."
The display of "verbatim" in the title or section name is environment-dependent. For example, on GitHub it appears large, but on GitLab it appears small. Other crates avoid this, and we would like to avoid it as well.
It is wonderful to put up the images. It makes the repository look many times better.
truck is mainly targeting B-rep, but actually scopes a variety of things. For example,
- giving smooth normals to meshes, the Loop subdivision, or
- truck_platform::Scene allows third parties to freely set drawing elements.
It is designed to be receptive to feature creep in the first place. We ourselves calculate priorities based on the company's business, but if one has a new pull request, for example regarding the mesh algorithm, we would welcome it!
Using clauses to itemize should violate the principle of separation of structure and appearance.
The license statement is very important as far as truck is concerned. This is because it is one of the biggest differences from OCCT, which is distributed under the LGPL. In general, it is better to leave it only to the upper right corners of GitHub and crates.io.
Tutorials has been compiled with Examples into Usage at this time. Thanks for correcting the wording.

About principles

The word "trendy"

The word "trendy" is controversial in some circles. I admit that "Modern" is better. On the other hand, I do not think "trendy" is too far from my original intention. In general, industries that fail to keep up with the tide tend to decline due to the lack of an influx of talent. If MFC is still active at the first company one joins after getting Ph.D., they concerned about their career 10 years later (this may be a bit of an extreme example, but it is a true story that happened.) I do not want young people to hesitate to contribute to this OSS. It is easy to fall into the 0 or 100 argument. However, in any case, it is rare to be able to obtain a large budget at one time. Without gradually raising small achievements, a decade project cannot continue. At least there should be a reasonable demand for a small application that can display STEP on a browser without server communication.

WebGPU and `wgpu`

WebGPU and wgpu are different concepts. truck depends much more deeply on cgmath, spade, and serde than wgpu. The behavior in WebGPU is, of course, a novelty, but it implicitly emphasizes the behavior in the browser. Running on browser is one of the justifications for going to the trouble of creating a new CAD Kernel. In recent years, AutoCAD has been talking about a full port to the browser. However, at the very least, a set of modules that give a commensurate amount of wasm for the size of the web application should not yet have been developed.

Why Rust?

Some have argued "is safety the only reason to adopt Rust?" In fact, I started developing truck because of FreeCAD's repeated freezes and OCCT's core dumping. However, I also got many more important benefits in the development process. One is the high level of abstraction provided by generics. truck does not fully mesh when meshing, but instead once generates a boundary representation with polylines and polygon meshes as the geometry. This can be implemented efficiently because the topology is defined in a well-defined, independent module using generics. In the future, STEP will be easily loaded into CAD systems with unique geometric structures, such as SketchUp.

Safety

The revision of this sentence about safety is correct now. Not so long ago I was actually hesitant about declaring everything to be written in safe. Using low-level packages like wgpu, sometimes unsafe cannot be avoided well. bytemuck's derive macro works well now.

ricosjp / truck