README

A PHP Library to plot graphs and figures on a xy(-two-dimensional)-plane.

1. Features

PHP-Plotter2d provides basic features to plot graphs and figures on a xy(-two-dimensional)-plane.

1.1. Canvas

You can draw figures freely on the canvas, such as: Pixels, Lines, Boxes, Circles, Ellipses, Polygons and Bezier Curves. You can also put Text or Fill the canvas with a specific color. You can save the Canvas to a file.

1.2. Plotarea

You can put figures within the Plotarea by just specifying the coordinates on the xy-plane without having to consider the pixel coordinates on the image. Transformer automatically maps the coordinates on the xy-plane to pixel coordinates on the image. Plotarea is automatically placed on the Canvas. You can adjust the position and the size of Plotarea on the Canvas.

1.3. Transformer

You can use only Transformer separately from Canvas and Plotarea.

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. Contents

• 1. Features
  • 1.1. Canvas
  • 1.2. Plotarea
  • 1.3. Transformer
• 2. Contents
• 3. Requirements
• 4. Installation
• 5. Usage
  • 5.1. Handling Canvas
  • 5.2. Handling Plotarea
  • 5.3. Handling Transformer
• 6. Examples
• 7. LICENSE

3. Requirements

• PHP 8.1 or later

• Imagick PHP Extension

  Check with commands:

  php -i | grep imagick

• Composer

4. Installation

composer require macocci7/php-plotter2d

5. Usage

5.1. Handling Canvas

To draw figures on the Canvas, create an instance of Canvas at first. Use Plotter::make() method to get an instance of Canvas. Pass the width and height of the Canvas in the canvasSize parameter.

<?php

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

use Macocci7\PhpPlotter2d\Plotter;

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

Now, you can draw figures on the Canvas with draw* methods.

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

You can save the image into a file with save method.

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

Available methods to draw on the Canvas:

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

fill()

fills the Canvas with the specified color.

drawPixel()

draws a pixel.

drawLine()

draws a line.

drawBox()

draws a box.

Note: null value for a color code results in transparent.

drawCircle()

draws a circle.

Note: null value for a color code results in transparent.

drawEllipse()

draws an ellipse.

Note: null value for a color code results in transparent.

drawArc()

draws an arc.

Note: null value for a color code results in transparent.

drawEllipticalArc()

draws an elliptical arc.

Note: If a non-null background color is specified, or true is specified for the withSide argument, an elliptical sector connecting the center of the ellipse and the elliptical arc will be drawn.

Note: null value for a color code results in transparent.

drawPolygon()

draws a polygon.

Note: null value for a color code results in transparent.

drawBezier()

draws a Bezier curve.

Note: null value for a color code results in transparent.

drawText()

draws text.

5.2. Handling Plotarea

To plot figures within the Plotarea, ceate an instance of Canvas with the parameters of viewport and plotarea.

viewport is the definition of the visible area of the xy-plane, which consists of arrays of x and y ranges.

plotarea has five attributes: offset, width, height, backgroundColor and 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'
);

Now, you can plot figures within the Plotarea by using plot* methods with coordinates on the xy-plane.

// 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');

When you set $plotarea['placeAutomatically'] as false, you need to use placePlotarea() method to place Plotarea on the Canvas after using plot* methods.

This is expected to avoid slowdowns when using the plot* methods frequently, and unexpected results when making the background of Plotarea transparent.

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

Available plot* methods to plot figures within the Plotarea:

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

plotFill()

fills the Plotarea with the specified color.

plotPixel()

plots a pixel within the Plotarea.

plotLine()

plots a line within the Plotarea.

plotBox()

polots a box within the Plotarea.

Note: null value for a color code results in transparent.

plotCircle()

plots a ciele within the Plotarea.

Note: If the viewport aspect ratio and the plotarea aspect ratio are not equal, plotCircle() draws an ellipse.

Use plotPerfectCircle() if you want to plot a perfect circle regardless of transformation rate.

Note: null value for a color code results in transparent.

plotPerfectCircle()

plots a perfect ciele within the Plotarea regardless of transformation rate.

Note: Specify the radius in pix.

Note: null value for a color code results in transparent.

plotEllipse()

plots an ellipse within the Plotarea.

Note: null value for a color code results in transparent.

plotArc()

plots an arc within the Plotarea.

Note: If the viewport aspect ratio and the plotarea aspect ratio are not equal, plotArc() draws an elliptical arc.

Note: null value for a color code results in transparent.

plotPolygon()

plots a polygon within the Plotarea.

Note: null value for a color code results in transparent.

plotBezier()

plots a Bezier curve within the Plotarea.

Note: null value for a color code results in transparent.

plotText()

plots text within the Plotarea.

plotGridHorizon()

plots horizontal grids within the Plotarea.

Note: If 0 is passed to $interval, $interval will be set to the automatically calculated optimal value.

plotGridVertical()

plots vertical grids within the Plotarea.

Note: If 0 is passed to $interval, $interval will be set to the automatically calculated optimal value.

plotGridValuesX()

plots grid values on the x-axis within the Plotarea.

Note: If 0 is passed to $interval, $interval will be set to the automatically calculated optimal value.

plotGridValuesY()

plots grid values on the y-axis within the Plotarea.

Note: If 0 is passed to $interval, $interval will be set to the automatically calculated optimal value.

plotAxisX()

plots x-axis with within the Plotarea.

plotAxisY()

plots x-axis with within the Plotarea.

plotAxisLabelO()

plots the origin label within the Plotarea.

plotAxisLabelX()

plots the x-axis label within the Plotarea.

plotAxisLabelY()

plots the y-axis label within the Plotarea.

plotScaleX()

plots the x-axis scale within the Plotarea.

Note: If 0 is passed to $interval, $interval will be set to the automatically calculated optimal value.

plotScaleY()

plots the y-axis scale within the Plotarea.

Note: If 0 is passed to $interval, $interval will be set to the automatically calculated optimal value.

5.3. Handling Transformer

To use Transformer, create an instance of Transformer at first.

use Macocci7\PhpPlotter2d\Transformer;

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

Now, you can use get* methods.

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

This code results in:

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

Available methods:

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

getRateX()

returns the transformation rate of x,

which is defined as:

(width of plogarea) / (range of x)

getRateY()

returns the transformation rate of y,

which is defined as:

(height of plotarea) / (range of y)

getCoord()

returns the transformed coordinate.

For example,

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

returns

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

getCoords()

returns multiple transformed coordinates as an arrray.

For example,

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

returns

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

getSpanX()

returns the transformed span of the x-direction component.

getSpanY()

returns the transformed span of the y-direction component.

6. Examples

• BasicUsage.php >> results in:

  

• DrawOnCanvas.php >> results in:

  

• PlotWithinPlotarea.php >> results in:

  

• Graffiti.php >> results in:

  

• GraphLogCurve.php >> results in:

  

• UseTransformer.php >> results in:

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

7. LICENSE

MIT

Copyright 2024-2025 macocci7