README

一个PHP库，用于在xy(-二维)-平面上绘制图表和图形。

1. 功能

PHP-Plotter2d 提供在xy(-二维)-平面上绘制图表和图形的基本功能。

1.1. 画布

您可以在画布上自由绘制图形，例如：像素、线条、矩形、圆形、椭圆、多边形和贝塞尔曲线。您还可以在画布上添加文本或用特定颜色填充画布。您可以将画布保存到文件。

1.2. 绘图区域

您可以通过在xy平面上指定坐标，将图形放入绘图区域中，而无需考虑图像上的像素坐标。Transformer自动将xy平面上的坐标映射到图像上的像素坐标。绘图区域自动放置在画布上。您可以在画布上调整绘图区域的位置和大小。

1.3. Transformer

您可以使用Transformer单独于画布和绘图区域。

use Macocci7\PhpPlotter2d\Transformer;

$transformer = new Transformer(
    viewport: ['x' => [-1, 4], 'y' => [-2, 3]],
    plotarea: [
        'width' => 400,
        'height' => 400,
    ],
);

$points = $transformer->getCoords([
    [-0.5, -1.2],
    [1.3, 0.6],
    [3.4, 2.8],
]);

2. 内容

• 1. 功能
  • 1.1. 画布
  • 1.2. 绘图区域
  • 1.3. Transformer
• 2. 内容
• 3. 要求
• 4. 安装
• 5. 使用方法
  • 5.1. 处理画布
  • 5.2. 处理绘图区域
  • 5.3. 处理Transformer
• 6. 示例
• 7. LICENSE

3. 要求

• PHP 8.1 或更高版本
• Imagick PHP 扩展
• Composer

4. 安装

composer require macocci7/php-plotter2d

5. 使用方法

5.1. 处理画布

要在画布上绘制图形，首先创建一个Canvas实例。使用Plotter::make()方法获取Canvas实例。在canvasSize参数中传递画布的宽度和高度。

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use Macocci7\PhpPlotter2d\Plotter;

$canvas = Plotter::make(
    canvasSize: ['width' => 800, 'height' => 400],  // required
);

现在，您可以使用draw*方法在画布上绘制图形。

$canvas->drawText('Basic Usage', 300, 20, 32, valign: 'top');

您可以使用save方法将图像保存到文件。

$canvas
    ->drawText('Handling Canvas', 300, 20, 32, valign: 'top')
    ->save('img/HandlingCanvas.png');

在画布上绘制图形的可用方法

• fill()
• drawPixel()
• drawLine()
• drawBox()
• drawCircle()
• drawEllipse()
• drawArc()
• drawEllipticalArc()
• drawPolygon()
• drawBezier()
• drawText()

fill()

用指定颜色填充画布。

drawPixel()

绘制一个像素。

drawLine()

绘制一条线。

drawBox()

绘制一个矩形。

注意：颜色代码的null值会导致透明。

drawCircle()

绘制一个圆形。

注意：颜色代码的null值会导致透明。

drawEllipse()

绘制一个椭圆。

注意：颜色代码的null值会导致透明。

drawArc()

绘制一个圆弧。

注意：颜色代码的null值会导致透明。

drawEllipticalArc()

绘制一个椭圆弧。

注意：如果指定了非空背景颜色，或者为withSide参数指定了true，将绘制一个连接椭圆中心和椭圆弧的椭圆扇区。

注意：颜色代码的null值会导致透明。

drawPolygon()

绘制一个多边形。

注意：颜色代码的null值会导致透明。

drawBezier()

绘制一个贝塞尔曲线。

注意：颜色代码的null值会导致透明。

drawText()

绘制文本。

5.2. 处理绘图区域

要在绘图区域内绘制图形，请使用带有viewport和plotarea参数的Canvas实例。

viewport是xy平面的可见区域定义，由x和y的范围数组组成。

plotarea有五个属性：offset、width、height、backgroundColor和placeAutomatically。

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use Macocci7\PhpPlotter2d\Plotter;

$canvas = Plotter::make(
    canvasSize: [
        'width' => 800,     // required
        'height' => 400,    // required
    ],
    viewport: [
        'x' => [-5, 5],     // -5 <= x <= 5
        'y' => [-5, 5],     // -5 <= y <= 5
    ],
    plotarea: [
        // 20pix from left edge, 30pix from top edge
        // default=(10% of the canvas)
        'offset' => [20, 30],
        'width' => 640, // in pix, default=(80% of the canvas)
        'height' => 360 // in pix, default=(80% of the canvas)
        'backgroundColor' => '#dddddd', // defautl='#ffffff'
        'placeAutomatically' => false, // default=true
    ],
    backgroundColor: '#0000cc',  // optional, default='#ffffff'
);

现在，您可以通过使用带有xy平面坐标的plot*方法在绘图区域内绘制图形。

// boxrange: (-3.5, 4.2) - (2.5, 2.3)
// backgroundColor: '#ffff99'
// borderWidth: 1 (pix)
// borderColor: '#0000ff'
$canvas
    ->plotBox(-3.5, 4.2, 2.5, 2.3, '#ffff99', 1, '#0000ff')
    ->save('img/HandlingPlotarea.png');

当您将$plotarea['placeAutomatically']设置为false时，您需要在使用plot*方法后使用placePlotarea()方法将绘图区域放置在画布上。

这可以避免在使用plot*方法时出现速度减慢，并避免在将绘图区域的背景设置为透明时出现意外的结果。

$canvas
    ->plotBox(-3.5, 4.2, 2.5, 2.3, '#ffff99', 1, '#0000ff')
    ->placePlotarea()
    ->save('img/HandlingPlotarea.png');

在绘图区域内绘制图形的可用plot*方法

• plotFill()
• plotPixel()
• plotLine()
• plotBox()
• plotCircle()
• plotPerfectCircle()
• plotEllipse()
• plotArc()
• plotPolygon()
• plotBezier()
• plotText()
• plotGridHorizon()
• plotGridVertical()
• plotGridValuesX()
• plotGridValuesY()
• plotAxisX()
• plotAxisY()
• plotAxisLabelO()
• plotAxisLabelX()
• plotAxisLabelY()
• plotScaleX()
• plotScaleY()

plotFill()

使用指定颜色填充 Plotarea。

plotPixel()

在 Plotarea 内绘制一个像素。

plotLine()

在 Plotarea 内绘制一条线。

plotBox()

在 Plotarea 内绘制一个矩形。

注意：颜色代码的null值会导致透明。

plotCircle()

在 Plotarea 内绘制一个圆。

注意：如果 viewport aspect ratio 和 plotarea aspect ratio 不相等，plotCircle() 会绘制一个椭圆。

如果您想绘制一个不受变换率影响的完美圆，请使用 plotPerfectCircle()。

注意：颜色代码的null值会导致透明。

plotPerfectCircle()

无论变换率如何，在 Plotarea 内绘制一个完美的圆。

注意：请指定半径（单位：像素）。

注意：颜色代码的null值会导致透明。

plotEllipse()

在 Plotarea 内绘制一个椭圆。

注意：颜色代码的null值会导致透明。

plotArc()

在 Plotarea 内绘制一个圆弧。

注意：如果 viewport aspect ratio 和 plotarea aspect ratio 不相等，plotArc() 会绘制一个椭圆形圆弧。

注意：颜色代码的null值会导致透明。

plotPolygon()

在 Plotarea 内绘制一个多边形。

注意：颜色代码的null值会导致透明。

plotBezier()

在 Plotarea 内绘制一个贝塞尔曲线。

注意：颜色代码的null值会导致透明。

plotText()

在 Plotarea 内绘制文本。

plotGridHorizon()

在 Plotarea 内绘制水平网格。

注意：如果将 0 传递给 $interval，则 $interval 将设置为自动计算的优化值。

plotGridVertical()

在 Plotarea 内绘制垂直网格。

注意：如果将 0 传递给 $interval，则 $interval 将设置为自动计算的优化值。

plotGridValuesX()

在 Plotarea 内绘制 x 轴上的网格值。

注意：如果将 0 传递给 $interval，则 $interval 将设置为自动计算的优化值。

plotGridValuesY()

在 Plotarea 内绘制 y 轴上的网格值。

注意：如果将 0 传递给 $interval，则 $interval 将设置为自动计算的优化值。

plotAxisX()

在 Plotarea 内绘制 x 轴。

plotAxisY()

在 Plotarea 内绘制 x 轴。

plotAxisLabelO()

在 Plotarea 内绘制原点标签。

plotAxisLabelX()

在 Plotarea 内绘制 x 轴标签。

plotAxisLabelY()

在 Plotarea 内绘制 y 轴标签。

plotScaleX()

在 Plotarea 内绘制 x 轴刻度。

注意：如果将 0 传递给 $interval，则 $interval 将设置为自动计算的优化值。

plotScaleY()

在 Plotarea 内绘制 y 轴刻度。

注意：如果将 0 传递给 $interval，则 $interval 将设置为自动计算的优化值。

5.3. 处理Transformer

要使用 Transformer，首先创建一个 Transformer 实例。

use Macocci7\PhpPlotter2d\Transformer;

$transformer = new Transformer(
    viewport: ['x' => [-1, 4], 'y' => [-2, 3]],
    plotarea: [
        'width' => 400,
        'height' => 400,
    ],
);

现在，您可以使用 get* 方法。

$x = -0.5;
$y = 2.8;
$coord = $transformer->getCoord($x, $y);
echo "({$x}, {$y}) -> ({$coord['x']}, {$coord['y']})" . PHP_EOL;

此代码的结果是

(-0.5, 2.8) -> (40, 16)

可用方法

• getRateX()
• getRateY()
• getCoord()
• getCoords()
• getSpanX()
• getSpanY()

getRateX()

返回 x 的变换率，

定义为

(width of plogarea) / (range of x)

getRateY()

返回 y 的变换率，

定义为

(height of plotarea) / (range of y)

getCoord()

返回变换后的坐标。

例如，

$transformer->getCoord(-0.5, 2.8);

返回

['x' => 40, 'y' => 16]

getCoords()

返回多个变换后的坐标作为数组。

例如，

$transformer->getCoords([
    [-0.5, -1.2],
    [1.3, 0.6],
    [3.4, 2.8],
]);

返回

[
    0 => [40, 336],
    1 => [184, 192],
    2 => [352, 16],
]

getSpanX()

返回 x 方向组件的变换跨度。

getSpanY()

返回 y 方向组件的变换跨度。

6. 示例

• BasicUsage.php >> 结果为

  

• DrawOnCanvas.php >> 结果为

  

• PlotWithinPlotarea.php >> 结果为

  

• Graffiti.php >> 结果为

  

• GraphLogCurve.php >> 结果为

  

• UseTransformer.php >> 结果为

  (-0.5, 2.8) -> (40, 16)

7. LICENSE

MIT

版权所有 2024 macocci7