附录

API和实施说明

外部接口

该模块的大多数用户将使用以下两个功能之一。它们提供了一个高级接口。它们也可以直接访问，因为 aafigure.process 分别 aafigure.render 。

aafigure.aafigure.process(input, visitor_class, options=None)

使用给定的访问者类解析输入并呈现。

参数:

  • input -- 将图像作为文本的字符串或类似文件的对象。

  • visitor_class -- 一个类对象，它将用于呈现结果图像。

  • options -- 包含设置的词典。什么时候 None ，则使用缺省值。

返回:

实例化 visitor_class 而且图像已经与访客一起处理过了。

例外情况:

此函数可以引发 UnsupportedFormatError 如果不支持指定的格式，则引发异常。

aafigure.aafigure.render(input, output=None, options=None)

将ASCII艺术图形渲染到文件或类似文件的文件。

参数:

  • input -- 如果 input 是基本字符串子类(str或unicode)，包含在 input 被渲染。如果 input is a file-like object, the text to render is taken using `` Input.read()。

  • output -- 如果没有 output 则以字符串的形式返回生成的渲染图像。如果输出是BaseString子类，则文件名为 output 将创建内容并将渲染图像保存在其中。如果 output 是一个类似文件的对象， output.write() 用于保存渲染的图像。

  • options -- 包含设置的词典。什么时候 None ，则使用缺省值。

返回:

此函数返回一个元组 (visitor, output) ，在哪里 visitor 是呈现图像的访问者实例，并且 output 对象请求的图像。 output 参数(a str 如果是这样的话 None ，或者是类似文件的对象，否则，您应该 close() 如果需要的话)。

例外情况:

此函数可以引发 UnsupportedFormatError 如果不支持指定的格式，则引发异常。

命令行功能在 main 功能。

aafigure.aafigure.main()

实现一个用作命令行程序的有用的Main

内部接口

核心功能在以下类中实现。

class aafigure.aafigure.AsciiArtImage(text, options=None)

此类包含一个ASCII艺术图形，并具有解析它的方法。生成的形状列表也存储在这里。

镜像的解析分两步进行：

  1. 水平字符串检测。

  2. 通用形状检测。

形状或字符串中使用的每个字符都有标签。以便进一步的搜索不会再次包括它(例如，字符串中的文本触及填充)，分别可以正确使用它(例如，当两行或更多行命中时连接字符)。

__init__(text, options=None)

取一个ASCII艺术图形并将其存储，准备 recognize

recognize()

尝试将ASCII图稿转换为矢量图形。结果存储在 self.shapes 。

图像是使用以下形状构建的。访问者类必须能够处理这些类型。

class aafigure.shapes.Arc(start, start_angle, end, end_angle, start_curve=True, end_curve=True)

两点之间的光滑弧线

class aafigure.shapes.Circle(center, radius)

带中心坐标和半径的圆。

class aafigure.shapes.Group(shapes=None)

一组形状

class aafigure.shapes.Label(position, text)

位于某个位置的文本标签

class aafigure.shapes.Line(start, end, thick=False)

具有起点和终点的直线。两端都可以有箭头

class aafigure.shapes.Point(x, y)

只有一分。此类的主要用途是表示其他形状的坐标。

class aafigure.shapes.Rectangle(p1, p2)

具有两个边坐标的矩形。

aafigure.shapes.group(list_of_shapes)

如果形状数大于1，则返回一个组

aafigure.shapes.point(obj)

返回一个Point实例。-如果对象已经是Point实例，则按原样返回-复数转换为点-具有两个元素(x，y)的元组

选项

这个 options 词典在许多地方被使用。有效密钥(及其默认值)为：

定义输出：

file_like <str>：

使用给定的类似文件的对象来编写输出。该对象需要支持 .write(data) 方法。

format <str>：

选择后端/输出格式：‘svg’，‘pdf’，‘png’，所有PIL支持的位图格式都可以使用，但只有少数有意义。将线条图另存为PNG格式而不是JPEG格式时，压缩效果很好，质量也更好。SVG将获得最好的质量，尽管目前并非所有浏览器都支持这种矢量图像格式(默认： 'svg' )。

影响图像解析方式的选项：

textual <bool>：

禁用水平填充检测。仅当填充垂直高度至少为2个字符时才会检测到填充(默认为： False )。

textual_strict <bool>：

完全禁用填充检测。(默认： False )。

proportional <bool>：

使用成比例的字体。比例字体通常比等宽字体看起来更好，但如果您需要它们看起来尽可能类似于ASCII艺术(默认： False )。

视觉属性：

background <str>：

表单中的背景色 #rgb 或 #rrggbb ， not 对于SVG输出(默认： #000000 )。

foreground <str>：

表单中的前景色 #rgb 或 #rrggbb (默认： #ffffff )。

fill <str>：

在表单中填充颜色 #rgb 或 #rrggbb (默认：与相同 foreground 颜色)。

line_width <浮动>：

更改行，当前仅支持SVG(默认： 2.0 )。

scale <浮动>：

放大或缩小图像(默认： 1.0 )。

aspect <浮动>：

更改纵横比。实际上，是图像的宽度乘以该系数。默认设置 1 当形状在水平或垂直方向绘制时必须具有相同的外观时，此选项非常有用。然而，0.5看起来更像最初的ASCII，甚至更小的系数可能对时序图之类的有用。但存在文本被裁剪或被绘制在其旁边的对象上的风险。

拉伸是在绘制箭头或圆之前完成的，这样它们仍然很好看(默认： 1.0 )。

其他选项：

debug <bool>：

目前，它只打印原始的ASCII艺术图形文本(默认： False )。

来访者

可用于呈现图像的访问器必须提供以下函数(它由 process() )

class your.Visitor
visit_image(aa_image)

一个 AsciiArtImage 实例作为参数传递。访问函数需要实现一个循环来处理 shapes 属性。

此函数必须负责实际输出结果图像，或者它必须以对调用者有用的形式提供数据 (process() 例如，返回访问者以便可以读取结果)。

存根类示例：

class Visitor:
    def visit_image(self, aa_image):
        self.visit_shapes(aa_image.shapes)

    def visit_shapes(self, shapes):
        for shape in shapes:
            shape_name = shape.__class__.__name__.lower()
            visitor_name = 'visit_%s' % shape_name
            if hasattr(self, visitor_name):
                getattr(self, visitor_name)(shape)
            else:
                sys.stderr.write("WARNING: don't know how to handle shape %r\n"
                    % shape)

    def visit_group(self, group):
        self.visit_shapes(group.shapes)

    # for actual output implement visitors for all the classes in
    # aafigure.shapes:

    def visit_line(self, lineobj):
        ...
    def visit_circle(self, circleobj):
        ...
    etc...

源树

这些源代码可以使用以下命令签出 bazaar:

bzr lp:aafigure

中的文件 aafigure 套餐：

aafigure.py

ASCII艺术解析器。这是主模块。

shapes.py

定义几何形状(如线、圆等)的类层次。

error.py

定义常见的例外类。

aa.py

ASCII艺术输出后端。用于测试，对最终用户没有真正的用处。

pdf.py

PDF输出后端。这要看报告实验室了。

pil.py

位图输出后端。使用PIL，它可以编写PNG、JPEG和更多格式。

svg.py

SVG输出后端。

中的文件 docutils 目录：

aafigure_directive.py

实现 aafigure Docutils指令，该指令获取这些ASCII艺术图形并生成图形。

这个 aafigure 模块包含解析ASCII艺术图形并创建形状列表的代码。不同的输出模块可以遍历形状列表并写入图像文件。

TODO

  • 符号检测：扫描ASCII图像中的预定义形状，并将它们作为符号从库中输出

  • 统一建模语言的符号库，流程图，电子原理图，...

  • 嵌入图像的方式是一种技巧(通过原始节点插入标签...)

  • 寻找引入色彩的方法。想法：

    • 有一个：选项：设置颜色标签。接触此类标记的形状将继承其颜色。标记将在ASCII源文件Tough：：中可见

      .. aafig::
    :colortag: 1:red, 2:blue

    1--->  --->2

    • :color: x,y,color 但计算坐标并不是那么有趣

    缺点：两者的实现都很复杂，需要搜索属于一起的形状。也不总是希望这样，例如，当一条线接触到一个框时，两者具有相同的颜色

  • Aafigure可能需要像这样的论点 font-family ..

  • 不包括在字符串中的标点符号(现在有所改进，但如果它具有图形意义，则选择，即使它没有意义)，字符串中的下划线很难检测...

  • 虚线？ ... 例如，用于 ---...--- 插入一条虚线而不是3个文本点。垂直虚线也应适用于 : 。

  • 对属于某个对象的形状进行分组，以便在矢量绘图程序中更轻松地导入和更改图形。 [partly done]

  • 路径优化器，在可以使用长行的情况下，会输出许多小行。

Aafigure的第三方集成

还有其他整合了aafigure的项目。以下项目由其他开发人员维护。

MediaWiki插件

MediaWiki 是一种流行的 WikiWikiWeb 它还用于 WikiPedia. 可以在以下位置找到插件：http://www.mediawiki.org/wiki/Extension:Aafigure

AsciiDoc插件

AsciiDoc 是一种纯文本文档格式，可以转换为多种格式，如HTML或PDF。可在此处找到在此类文档中使用纯图形的插件：http://code.google.com/p/asciidoc-aafigure-filter/

作者和联系人

  • 克里斯·利奇提：原著作者

  • Leandro Lucarella：提供了许多补丁

项目页面在https://launchpad.net/aafigure，它应该用来报告错误和功能请求。

许可证

版权所有(C)2006-2017 aafigure-团队保留所有权利。

在满足以下条件的情况下，允许以源代码和二进制形式重新分发和使用，无论是否进行修改：

  • 源代码的再分发必须保留上述版权声明、此条件列表和以下免责声明。

  • 二进制形式的再分发必须在随分发提供的文档和/或其他材料中复制上述版权声明、此条件列表和以下免责声明。

  • 未经事先明确的书面许可，不得使用aafigure团队的名称或其贡献者的名称来支持或推广源自本软件的产品。

本软件由AAFIGURE团队按原样提供，任何明示或默示保证，包括但不限于对适销性和特定用途适用性的默示保证，均予以否认。在任何情况下，AAFIGURE团队均不对因使用本软件而造成的任何直接、间接、附带、特殊、惩罚性或后果性损害(包括但不限于替代产品或服务的采购；使用、数据或利润的损失；或业务中断)承担任何责任，无论是合同责任、严格责任或侵权行为(包括疏忽或其他)，即使已被告知此类损害的可能性。