SKIP 2 — scikit-image 宣言#

作者:

Juan Nunez-Iglesias <juan.nunez-iglesias@monash.edu>

作者:

Stéfan van der Walt <stefanv@berkeley.edu>

作者:

Josh Warner

作者:

François Boulogne

作者:

Emmanuelle Gouillart

作者:

Mark Harfouche

作者:

Lars Grüter

作者:

Egor Panfilov

作者:

Gregory Lee

状态:

活跃

类型:

流程

创建:

2018-12-08

解决:

决议:

skimage-版本:

0.16

摘要#

scikit-image 应采用以下文档作为其宣言。此宣言将在 scikit-image 首页和自述文件以及贡献者和核心开发者指南中占据突出位置。有关 API 和库未来的决策将参考此文档。（请参阅 SKIP 1 — scikit-image 治理和决策。）

2018 年 7 月，我（Juan）发布了一篇博文，广泛概述了我对 scikit-image 路线图的期望 [1]，但在最终确定之前请求了社区的意见。我认为我们已经收集了足够长的意见，可以继续正式采纳。大多数评论都是积极的，因此在下文中，我将仅在“被拒绝的想法”下总结“负面”评论。

详细说明#

（或：此提案解决了什么问题？）

在过去的几年里，scikit-image 变得有点“漂泊不定”，新的和旧的贡献者不断涌现，在当时添加他们需要的小部分内容，然后又消失一段时间。这很好，我们希望鼓励更多这样的贡献，但它也缺乏方向。此外，如果没有集中努力的路线图，许多贡献就会被搁置一旁，因为新贡献者很难达到我们严格（且大多未写成文字）的代码标准。

实现#

我们的使命#

scikit-image 旨在成为 Python 中科学图像分析的参考库。我们通过以下方式实现这一目标

  • 易于使用和安装。我们在承担新依赖项方面非常谨慎，有时会剔除现有依赖项，或者使它们成为可选的。我们 API 中的所有函数都有详尽的文档字符串，阐明了预期的输入和输出。

  • 提供一致的 API。从概念上讲，相同的参数在函数签名中具有相同的名称和位置。

  • 确保正确性。测试覆盖率接近 100%，并且代码在包含在库中之前至少由两位核心开发者审查。

  • 关注用户数据。我们有一个功能性的 [2] API，并且除非明确指示，否则不会修改输入数组。

  • 通过广泛的教学文档促进图像处理方面的教育。

我们的价值观#

  • 我们具有包容性。我们继续欢迎和指导正在做出首次贡献的新人。

  • 我们以社区为导向。关于 API 和功能的决策由用户的需求驱动，而不是由核心团队的意愿驱动。（请参阅 SKIP 1 — scikit-image 治理和决策。）

  • 我们主要服务于科学应用，而不是类似 Photoshop 或 GIMP 的“消费级”图像编辑。这通常意味着优先考虑 n 维数据支持，并拒绝对科学价值较低的“炫目”滤镜的实现。

  • 我们重视简单易读的实现，而不是追求极致的性能。易于理解的易读代码，对于新手和维护者来说，都更容易贡献新代码并防止错误。这意味着如果它可以将代码行减少两倍，例如，我们更倾向于接受 20% 的速度下降。

  • 我们重视教育和文档。所有函数都应具有 NumPy 风格的文档字符串 [3]，最好有示例，以及展示该函数如何在科学应用中使用的图库示例。核心开发者积极参与完成文档示例。

  • 我们不做魔法。我们使用 NumPy 数组而不是花哨的 façade 对象 [12]，并且我们更倾向于教育用户而不是代表他们做出决定。这并不排除合理的默认值。 [4]

本文档#

与 Python 之禅 [5] 和 PEP8 指导大多数 Python 代码的样式和实现细节一样，本指南旨在指导有关 scikit-image 未来决策，无论是代码风格、是否接受新功能，还是是否承担新依赖项等。

参考文献#

要了解更多有关本文档历史的信息，请阅读以下内容

  • 原始博文 [1]

  • GitHub 问题 [6]

  • image.sc 论坛帖子 [7]

  • SKIP GitHub 拉取请求 [8]

脚注

向后兼容性#

此 SKIP 正式化了 scikit-image 未成文的文化，因此它不会引起任何向后兼容性问题。

替代方案#

原始讨论中的两个主题最终被拒绝，详述如下

处理元数据#

在我的原始帖子中，我建议 scikit-image 应该在 1.0 之前具备某种形式的元数据处理功能。Mark Harfouche、Curtis Rueden 和 Dan Allan 等人建议 (a) scikit-image 可能不需要处理元数据，而是可以专注于成为一个强大的低级库，另一个像 XArray 这样的库可以使用它来包含元数据处理，以及 (b) 无论如何，元数据支持可以在以后添加，而不会破坏 1.0 API。我认为这些都是非常好的观点，此外，元数据处理非常困难，我不介意暂时将此问题排除在外。

魔法思维#

Philipp Hanslovsky 建议 [9]，关于“做魔法”，在某些情况下是可取的，一个好的解决方案是在非魔法层之上构建一个魔法层。我同意这种评估，但是，在 1.0 之前，scikit-image 应该保持非魔法层。

讨论#

请参阅下面的参考文献。

参考文献#

本页内容
显示源代码