BUG: Fix DOC and comment defects.

未关闭
#1,899 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 6 天内回复

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
一周以上
新手友好度
20/100
Issue 类型
缺陷
描述清晰度
基本清楚
活跃度
活跃
技术栈
cpp

调研方向

This is a maintainer audit of 15 separate defects, not one task, so pick a single checklist line and work from it. For the first grayscale item, start in src/simplnx/Utilities/ImageProcessing/MorphologyEngine.hpp near line 384 and check how the empty-kernel test treats offsets with dz != 0 when Z = 1. Done means that one probe (a {7, 3, 7} uint8 image with the Annulus kernel) returns the input and the fix is covered by a test.

由索引模型根据 Issue 内容生成。

描述

bug documentation

Summary

2026-11-13: PRs #1961, #1962, #1965, #1967, #1968, #1969, #1970, #1971 and #1972 were closed and combined into #1973, which is built and tested with the combined EbsdLib branch BlueQuartzSoftware/EbsdLib#86 (it holds EbsdLib #70 to #85, which were closed into it). Items that named one of these pull requests now also name #1973. No item is ticked until #1973 is merged.

We found these defects while we reviewed the port-regression fix branch for DREAM3D-NX. The branch does not fix them. They are already on develop.

We found them by reading code and by running review probes. We confirmed each item against develop 6dd86c67d. All line numbers and links below use that commit.

No item here is in #1861-#1880 or in the list of untracked findings.

This issue now holds documentation and comment defects only. Code defects are tracked in #1908 (CRASH, WRONG_DATA and ERROR) and in #1917 (MINOR). The moved code-defect items keep their lines here, struck through, with their new item numbers. Items D16 to D20 and the extra pages in item D11 were found while reviewing PR #1915 and checked on develop a7dffc440 (2026-11-04); their links use that commit. Items D21 and D22 were found while reviewing PR #1921 and checked on develop a7dffc440 (2026-11-05); their links use that commit.

The checklist has 22 items (D01 to D22). 16 are open: 13 DOCS and 3 MINOR (code comments). 6 moved: the 2 WRONG_DATA items and the ERROR item to #1908 (items L73 to L75), and the 3 MINOR code items to #1917 (items M19, M20 and M24). Refer to an item by its D number, for example "Fixes #1899 item D07".

Checklist

Documentation defects
  • D07 · DOCS · ComputeVectorColorsFilter · ComputeVectorColorsFilter.md:11 — The legend image Images/VectorColors.png has its Y axis flipped compared with the code, so users read the wrong direction from a color.

    • The code maps (0,1,0) (trend 90) to green (63, 191, 0). The legend draws green at the bottom (-Y) and shows violet at the point labeled (0,1,0).
    • (1,1,0) has the same problem. The code gives orange (159, 95, 0). The legend shows magenta at that label.
    • DREAM3D 6.5.171 uses the same formula, so the image is wrong, not the code.
  • D08 · DOCS · CropVertexGeometryFilter · CropVertexGeometryFilter.md:15 — The note says that the new Vertex Geometry and its arrays start with size 0, but preflight creates them with the input vertex count and execute shrinks them.

  • D09 · DOCS · ScalarSegmentFeaturesFilter · ScalarSegmentFeaturesFilter.md:25 — The page says that a neighbor joins when it differs by "less than" the tolerance, but the code uses <=, so a neighbor that differs by exactly the tolerance also joins.

  • D10 · DOCS · ScalarSegmentFeaturesFilter · ScalarSegmentFeaturesFilter.md:33 — The page suggests a tolerance "less than 1" and "around 0.05-0.1", but Scalar Tolerance is an int32 parameter, so a user cannot enter a fractional value.

  • D11 · DOCS · StandardDeviationProjectionImageFilter · StandardDeviationProjectionImageFilter.md:23 — The page says that in-memory inputs use slab staging, but an in-core DataStore takes the direct route ApplyAxisProjectionInMemory; only out-of-core or other stores use the staged routes.

  • D12 · DOCS · ConvertColorToGrayScaleFilter · ConvertColorToGrayScaleFilter.md:29 — The page says the filter accepts 4-component RGBA input and has an Output to New Attribute Matrix option, but the input parameter accepts only 3-component uint8 arrays and no such option exists.

    • The RGBA claim is also on lines 9 and 13.
  • D13 · DOCS · TriangleDihedralAngleFilter · TriangleDihedralAngleFilter.md:22 — The page says the output is 0° to 60°, but a face with a zero-length edge gets NaN, and the page does not mention NaN.

  • D16 · DOCS · AddBadDataFilter · AddBadDataFilter.md:33 — The section "What "Bad" Means in Output" says that the filter sets to 0 every array in the same Attribute Matrix as Boundary Euclidean Distances. The code sets to 0 the arrays in the Cell Data Attribute Matrix of the geometry. Line 47 of the same page says that Boundary Euclidean Distances can be in any Attribute Matrix, so the two statements disagree.

  • D17 · DOCS · ReadDREAM3DFilter · ReadDREAM3DFilter.md:17 — The page says that an imported object at a path that already exists "is replaced (overwritten)". But ImportH5ObjectPathsAction rejects this collision with error -6203, and an existing test asserts that error.

  • D18 · DOCS · WriteStatsGenOdfAngleFileFilter · WriteStatsGenOdfAngleFileFilter.md:37 — The example file does not match what the code writes. The example says "space delimited." but the code writes "Space delimited.". The example has no "# Euler angles are expressed in ..." line, but the code always writes one. The first two comment lines are also different ("before the header" and "Angles Input File" in the example, "before the data" and "ODF Angles Input File" in the code).

  • D20 · DOCS · RotateSampleRefFrameFilter (V&V) · deviations/RotateSampleRefFrameFilter.md:7 — The V&V pages link to vv/comparisons/RotateSampleRefFrameFilter/results.md for the comparison with 6.5.171 (also RotateSampleRefFrameFilter.md:103 and provenance/RotateSampleRefFrameFilter.md:33), but that file is not in the repository. Add the results file or remove the links.

  • D21 · DOCS · ExecuteProcessFilter · ExecuteProcessFilter.md:29 — The section "Blocking and Timeout" does not describe what the code does.

    • Should Block off: the page says that the pipeline moves on without waiting. But the code reads the output until the process ends and then calls process.wait(reproc::infinite), so the filter waits for the process in both modes. The only difference is that the log file is written every second while the process runs.
    • Timeout (ms): the page says that it is the maximum wait time when Should Block is on. But Timeout is used only in the stop actions (ExecuteProcess.cpp:73), which are used only when the process object is destroyed. drain and wait(reproc::infinite) do not use it, so Timeout does not limit the wait in either mode.
    • Line 9 says that any output can be found in the log file. With Should Block on, error output (stderr) is not written to the log file (#1861 ExecuteProcessFilter#5).
    • #1876 (ExecuteProcessFilter#2) will change how Timeout works. Rewrite this section in the same pull request as that fix, or after it.
  • D22 · DOCS · CreatePythonSkeletonFilter · CreatePythonSkeletonFilter.md:27 — Step 3 of "Updating an Existing Plugin" tells the user to give Name of Plugin and Human Name of Plugin. But with Use Existing Plugin on, both parameters are disabled (CreatePythonSkeletonFilter.cpp:68-69), and the algorithm uses only Existing Plugin Location and Filter Names. Step 3 must name only Filter Names. This is not #1822 (the human name is ignored when a new plugin is made).

Comments
  • D14 · MINOR · GeometryMath (SampleSurfaceMesh ray test) · GeometryMath.hpp:294 — Both DoesRayIntersectBox overloads (also lines 316-317) say "one point should fall in the box since the length is half the bounding box diameter", which is not correct.

    • On develop the ray length is half the diagonal of the feature bounding box (SampleSurfaceMesh.cpp:318). But bounds in this function is the bounding box of one face.
    • The test does not need one end point in the box, and it does not depend on the ray length.
    • The port-regression fix branch changes the ray length to the full feature diagonal. After that, the word "half" is also wrong. Rewrite or remove the comment.
  • D15 · MINOR · PointSampleTriangleGeometryFilter · TupleTransfer.hpp:567 — The comments of AbstractTupleTransfer and of the TransferTuple class and constructor describe only the two-sided face use ("cell-to-face", "side zero ... side one"), but PointSampleTriangleGeometryFilter also uses TransferTuple, with equal source and destination component counts.

    • The constructor @pre says "for face transfers", so it is not wrong. But a reader of the class comment does not learn about the point-sample use.
  • D19 · MINOR · AlignSectionsFeatureCentroidFilter, ComputeFeatureClusteringFilter, ReadH5EspritDataFilter · AlignSectionsFeatureCentroid.cpp:276 — The comments say that the code does not inspect the Result values of bulk-I/O calls. But the code checks each Result and returns on failure (lines 290-294), so the comments are stale. — PR #1967 (ReadH5EspritData part only) → combined into #1973

Related issues

  • #1908: one-off CRASH, WRONG_DATA and ERROR defects. It holds items L73 to L75 that moved from here.

  • #1917: MINOR code defects. It holds items M19, M20 and M24 that moved from here.

  • #1916: StringArray::deepCopy shares the string store with the original.

  • #1861: wrong Y basis in Ray.hpp. It is the same ray code as the GeometryMath comment item, but a different defect.

  • #1864: ComputeVectorColorsFilter mask tuple count. It is a different defect in the same filter.

  • #1873: kernel radius narrowing to an empty kernel. It is a different cause from the Annulus {0, 0, r} item.

  • #1875: singular local frame in FeatureFaceCurvatureFilter, and NaN output patterns. It does not list the underdetermined fit or the TriangleDihedralAngleFilter NaN documentation.

  • #1877: ReadVtkStructuredPointsFilter header tokens (CRLF type tokens). It does not cover the component count.

Out of scope

  • The binary morphology routes with the same Annulus {0, 0, r} problem. The port-regression fix branch fixes them.
  • WriteVtkRectilinearGridFilter scalar precision with {:f}. The port-regression fix branch fixes it.
  • WriteVtkRectilinearGridFilter coordinates written with %f. This is tracked separately (WriteVtkRectilinearGridFilter#3).
  • inf and nan tokens in the ASCII VTK writers. Both the old and the new formatters write them. This is a separate policy question.
Code defects
  • D01 · WRONG_DATA · GrayscaleDilate, GrayscaleErode, GrayscaleMorphologicalOpening, GrayscaleMorphologicalClosing, WhiteTopHat, BlackTopHat, MorphologicalGradient (ImageProcessing) · MorphologyEngine.hpp:384 — On a 2D image (Z = 1) with the Annulus kernel and radius {0, 0, r} (r > 0), every kernel offset is out of plane, so the output is a constant (dilate gives the type minimum, erode gives the type maximum, the gradient gives lowest - max, which is 1 for uint8) and not a copy of the input. Moved to #1908 item L73.
    • The kernel is not empty, because the Annulus with rx = ry = 0 keeps only the offsets (0, 0, dz) with dz != 0. So the copy-through checks se.offsets.empty() do not catch it.
    • Grayscale routes with this problem: Morphology2DBlockBody, MorphGradient2DBlockBody, MorphDirect, MorphGradientDirect and ApplyMorphologyCompositePipeline.
    • Probe on a {7, 3, 7} uint8 image: Dilate gives 0, Erode gives 255 (Direct and Scanline), Gradient gives 1, Opening gives 0 and Closing gives 255. The control kernel Annulus {0, 0, 0} copies the input on every route.
    • Suggested fix: when Z = 1, drop the offsets with dz != 0 before the empty-kernel check on each grayscale route.
    • The binary routes have the same problem. The port-regression fix branch fixes them.
  • D02 · WRONG_DATA · FeatureFaceCurvatureFilter · CalculateTriangleGroupCurvatures.cpp:302 — With Use Normals for Curve Fitting on, the cubic fit has 7 unknowns, but the code does not check that the patch has at least 7 triangles, so a small patch gives an underdetermined least-squares fit and the curvature values are arbitrary, with no warning. Moved to #1908 item L74.
    • The seed triangle is moved to the origin, so its row in the fit matrix is all zero. In practice the fit needs 7 triangles other than the seed.
    • The quadratic fit (option off, 3 unknowns) has the same problem when the patch has only 2 triangles.
  • D03 · ERROR · ReadVtkStructuredPointsFilter · ReadVtkStructuredPoints.cpp:1113 — The SCALARS component count is read with std::atoi, so a bad value is not detected: abc or 0 gives 0 components, a negative value wraps to a very large usize, and the reader then parses the next header from data bytes and fails with an unrelated error. Moved to #1908 item L75.
    • Suggested fix: parse the count with StringInterpretationUtilities::Convert<usize> and reject a count less than 1 with a clear error.
  • D04 · MINOR · ScalarSegmentFeaturesFilter · ScalarSegmentFeatures.cpp:209 — The fallback comparators get static_cast<T>(ScalarTolerance), so a negative tolerance wraps for unsigned types (uint64: -1 becomes UINT64_MAX, and every pair matches) and a large tolerance is truncated for small types (int8: 300 becomes 44). Moved to #1917 item M19.
    • The buffered path compares in float64 and does not have this problem.
    • The fallback runs only when areNeighborsSimilar() is called outside the buffered CCL, for example through the public executeCCL() after operator()().
  • D05 · MINOR · ScalarSegmentFeaturesFilter · ScalarSegmentFeatures.cpp:120 — In the fallback comparator, m_Data[index] - m_Data[neighIndex] overflows for int32 and int64 at the type limits (for example INT32_MAX - INT32_MIN), which is undefined behavior. Moved to #1917 item M20.
    • The class comment states this as a precondition, but nothing enforces it. The reach is the same as the item above.
  • D06 · MINOR · WriteVtkStructuredPointsFilter · WriteVtkStructuredPoints.cpp:223 — Follow-up: in ASCII mode, floats are written with fmt::format("{}"), so a subnormal value is written as a token such as 1e-45 (float32) or 5e-324 (float64), and some VTK readers reject such a token and lose the values after it. Moved to #1917 item M24.
    • Review probes: standalone VTK 9.6.2 and ParaView 6.0.0 both failed on the subnormal cases.
    • The port-regression fix branch changes WriteVtkRectilinearGridFilter to the same {} format. After that fix, both ASCII VTK writers have this behavior. Before it, the rectilinear writer wrote such values as 0.000000.
    • Decide on one policy for both writers, and test it with the target readers.
主要语言
C++
星标
18
派生
15
平均合并
4 天 23 小时
30 天内合并 PR
42

环境准备

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

BlueQuartzSoftware/simplnx 的其他 Issue

查看 BlueQuartzSoftware/simplnx 的全部 Issue

相似的 Issue

更多 C++ Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。