Pythonista中文文档：canvas

Pythonista中文文档

canvas — 矢量图像

简介

  canvas模块包含用于在iOS上创建非交互式2D矢量图形的功能。它适用于绘制简单的图形/图表或线条。

  所有功能都在一个单一的画布上工作，该画布显示在Pythonista的输出区域中。尽管目前尚无法通过编程方式执行此操作，但是可以将通过这种方式创建的图像导出到设备的照片库或复制到剪贴板。

  坐标系的原点位于左下角，坐标为浮点数。颜色通常表示为RGB（A），其分量范围为0.0-1.0。

  画一个红色圆圈的最简单的示例：

#绘制一个红色圆圈填满整个画布
import canvas
w = h = 512
canvas.set_size(w, h)
canvas.set_fill_color(1, 0, 0)
canvas.fill_ellipse(0, 0, w, h)

---

配置画布

  以下功能可用于配置画布的整体绘制行为。通常，您可以通过调用set_size()开始任何绘图。

  如果要提高图形的性能，则可能要在开始图形之前添加调用begin_updates()，最后以调用end_updates()来平衡。这基本上可以避免显示中间结果，从而加快处理速度，但是在处理工程图代码时查看这些中间结果通常也可能会有所帮助。

canvas.clear()
  清除画布。您也可以使用set_size() 功能清除画布，该功能还可以重置所有图形状态（例如，变换，填充颜色等）。

canvas.get_size()
  返回画布的大小作为宽度和高度的元组。

canvas.set_size(width, height)
  设置画布的大小（最小16x16，最大2048x2048）并重置所有图形状态（例如，变换，填充颜色等）。

canvas.begin_updates()
  开始一组绘图操作。直到end_updates()被调用，结果才可见 。这可以显著提高性能。

canvas.end_updates()
  强制将所有缓冲的图形显示在屏幕上

  （另请参见begin_updates()）

canvas.save_png(filename)
  将画布的当前内容保存到PNG文件。

---

设置绘图参数

  使用这些功能来影响随后的所有绘制操作。例如，调用set_fill_color()设置为红色将在随后的任何fill_rect()调用中绘制一个红色矩形，直到您设置其他颜色为止。

canvas.set_aa_enabled(flag)
  启用或禁用抗锯齿。

canvas.set_alpha(alpha)
  设置全局alpha值。

  （另请参见set_blend_mode()）

canvas.set_blend_mode(mode)
  设置活动混合模式。可以是混合模式下列出的常数之一 。

  （另请参见set_alpha()）

canvas.set_fill_color(r, g, b[, a])
  设置填充颜色。

canvas.set_line_width(width)
  设置线宽。

（另请参见set_stroke_color()）

canvas.set_stroke_color(r, g, b[, a])
  设置活动笔触颜色。

  （另请参见set_line_width()）

---

矢量绘图函数

  以下功能用于绘制矢量路径和形状。

  画布始终具有当前路径，可以使用add _...函数对其进行操作 。您可以使用add_line()，add_curve()等来构造任意复杂的路径 然后使用fill_path()或draw_path()来填充或描画路径。如果您打算填充路径，则可能要先使用close_path()关闭它。

  填充或绘制路径具有清除当前路径的副作用。

  下面的示例绘制带有一些可配置参数的星形：

#绘制开始
import canvas
from math import sin, cos, pi

def draw_star(x, y, inner_r, outer_r, jags):
    canvas.move_to(w / 2, h / 2 + inner_r)
    for i in range(jags * 2):
        angle = (2 * pi / jags) * i / 2
        r = inner_r if i % 2 == 0 else outer_r
        x = w / 2 + r * sin(angle)
        y = h / 2 + r * cos(angle)
        canvas.add_line(x, y)
    canvas.close_path()
    canvas.set_line_width(3)
    canvas.draw_path()

w = h = 600
jags = 7 #V形凹口的数目
inner_r = 120 #内半径
outer_r = 250 #外半径
canvas.set_size(w, h)
draw_star(w/2, h/2, inner_r, outer_r, jags)

canvas.add_curve(cp1x, cp1y, cp2x, cp2y, x, y)
  使用控制点（cp1x，cp1y）和（cp2x，cp2y）的向当前路径的（x，y）添加三次贝塞尔曲线。

（另见begin_path()，draw_path()，fill_path()）

canvas.add_ellipse(x, y, width, height)
  向当前路径添加一个椭圆。

  （另见begin_path()，draw_path()，fill_path()）

canvas.add_line(x, y)
  向当前路径添加一条直线。

  （另见begin_path()，draw_path()，fill_path()，move_to()）

canvas.add_quad_curve(cpx, cpy, x, y)
  以（cpx，cpy）作为控制点，向（x，y）的当前路径添加二次贝塞尔曲线。

  （另见begin_path()，draw_path()，fill_path()）

canvas.add_rect(x, y, width, height)
  在当前路径中添加一个矩形。

  （另见begin_path()，draw_path()，fill_path()）

canvas.begin_path()
  开始新的路径。使用add_line()，add_rect()等将形状添加到此路径然后使用draw_path()或fill_path()使其可见。

canvas.clip()
  将后续图形剪切到当前路径。

  （另请参见begin_path()）

canvas.close_path()
  关闭当前路径。

  （另见begin_path()，draw_path()，fill_path()）

canvas.draw_ellipse(x, y, width, height)
  在矩形中绘制椭圆

  （另请参见set_stroke_color()，set_line_width()）

canvas.draw_line(x1, y1, x2, y2)
  在两点之间画一条线

  （另请参见set_stroke_color()，set_line_width()）

canvas.draw_path()
  使用活动的线宽和颜色绘制当前路径的轮廓。

  （另见begin_path()，fill_path()，set_stroke_color()，set_line_width()）

canvas.draw_rect(x, y, width, height)
  绘制矩形的轮廓

  （另请参见set_stroke_color()，set_line_width()）

canvas.fill_ellipse(x, y, width, height)
  用矩形填充椭圆

  （另请参见draw_ellipse()）

canvas.fill_path()
  用活动的填充颜色填充当前路径。

  （另见begin_path()，draw_path()，set_fill_color()）

canvas.fill_pixel(x, y)
  用当前的填充颜色填充像素

canvas.fill_rect(x, y, width, height)
  填充矩形

canvas.move_to(x, y)
  将“笔”移动到给定点。

  （另请参见add_line()）

---

变换

  使用以下变换函数，您可以操纵画布的当前变换矩阵（CTM）。例如，这可以用于绘制旋转或缩放的形状。变换画布时，实际上是在更改坐标系，该坐标系会影响此更改之后的所有图形。

  仅临时应用变换通常很有用。可以使用save_gstate()和restore_gstate()函数来完成。 save_gstate()拍摄当前变换的快照（以及其他图形状态参数，例如填充颜色）并将其放在堆栈中。之后调用restore_gstate()将恢复放置在堆栈上的最后一个状态。

  如果您想完全重置任何变换，但又没有保存图形状态，则可以使用该set_size()功能。

以下示例绘制带有旋转标签的钟面：

# 绘制一个钟面
import canvas
from math import pi

canvas.set_size(600, 600)
canvas.set_fill_color(0.7, 0.7, 0.7)
canvas.fill_ellipse(0, 0, 600, 600)
canvas.set_fill_color(0, 0, 0)
canvas.fill_ellipse(290, 290, 20, 20)

for i in range(12):
    canvas.save_gstate()
    canvas.translate(300, 300)
    canvas.rotate(-2 * pi / 12.0 * i)
    canvas.set_fill_color(0, 0, 0)
    s = 40
    fnt = 'Helvetica-Bold'
    n = str(12 if i == 0 else i)
    w, h = canvas.get_text_size(n, fnt, s)
    canvas.draw_text(n, -w/2, 240, fnt, s)
    canvas.restore_gstate()

canvas.restore_gstate()
  将当前图形状态设置为最近用save_gstate()保存的状态。

canvas.rotate(angle)
  旋转当前变换矩阵。

  （另请参见save_gstate()，restore_gstate()）

canvas.save_gstate()
  将当前图形状态（变换，所选颜色等）的副本推入图形状态堆栈。

  （另请参见restore_gstate()）

canvas.scale(sx, sy)
  缩放当前变换矩阵。

  （另请参见save_gstate()，restore_gstate()）

canvas.translate(tx, ty)
  翻译当前的变换矩阵。

  （另请参见save_gstate()，restore_gstate()）

---

绘制位图图像

  尽管它主要是为矢量图形设计的，但canvas模块也具有一些用于绘制位图图像的功能，类似于scene 模块。您可以绘制命名的图像或剪贴板当前的内容。

canvas.draw_image(image_name, x, y[, width, height])
  在矩形中绘制具有给定名称的图像。如果省略了宽度和高度，则以其自然尺寸绘制图像。

canvas.draw_clipboard(x, y, width, height)
  在剪贴板中以给定的矩形绘制图像。

canvas.get_clipboard_size()
  以磅为单位，以宽度和高度的元组返回剪贴板中图像的大小。在视网膜屏幕上，一个点对应两个像素。如果剪贴板为空，则返回（0,0）。

canvas.get_image_size(image_name)
  以给定名称返回图像的大小，以宽度和高度的元组为单位。在视网膜屏幕上，一个点对应两个像素。如果不存在具有该名称的图像，则返回（0，0）。

---

绘制文本

  canvas模块具有用于绘制和测量文本两个简单的功能。

  绘制文字的颜色draw_text()取决于之前对set_fill_color()的调用。

canvas.draw_text(text, x, y, font_name=’Helvetica’, font_size=16.0)
  在给定点绘制一行文本。该点表示线的原点，即其左下角。

canvas.get_text_size(text, font_name=’Helvetica’, font_size=16.0)
  获取由draw_text()函数绘制的文本行的大小，以(width, height)的元组表示。

---

混合模式

  以下混合模式可用于set_blend_mode()：

canvas.BLEND_NORMAL
canvas.BLEND_MULTIPLY
canvas.BLEND_DIFFERENCE
canvas.BLEND_SCREEN
canvas.BLEND_OVERLAY
canvas.BLEND_DARKEN
canvas.BLEND_LIGHTEN
canvas.BLEND_COLOR_DODGE
canvas.BLEND_COLOR_BURN
canvas.BLEND_SOFT_LIGHT
canvas.BLEND_HARD_LIGHT
canvas.BLEND_DIFFERENCE
canvas.BLEND_EXCLUSION
canvas.BLEND_HUE
canvas.BLEND_SATURATION
canvas.BLEND_COLOR
canvas.BLEND_LUMINOSITY
canvas.BLEND_CLEAR
canvas.BLEND_COPY
canvas.BLEND_SOURCE_IN
canvas.BLEND_SOURCE_OUT
canvas.BLEND_SOURCE_ATOP
canvas.BLEND_DESTINATION_OVER
canvas.BLEND_DESTINATION_ATOP
canvas.BLEND_XOR
canvas.BLEND_PLUS_DARKER
canvas.BLEND_PLUS_LIGHTER