[ann] impending gonum/plot API breakage

[Seb Binet]

hi there,

this is a short announcement to let you know that github.com/gonum/plot will experience a short API breakage in the near future:

- vg: migrate draw.Point+draw.Rectangle back to vg

https://github.com/gonum/plot/pull/261

- vg: make Canvas and Path APIs use vg.Points

https://github.com/gonum/plot/pull/266

- vg,plotter: add vg.Canvas.DrawImage and plotter.Image

https://github.com/gonum/plot/pull/256

The migration should happen after #256 has been LGTM'ed (plus some breathing time)

I will first collect feedback here, on gonum-dev, and once this announcement received enough backing, I'll send it to golang-nuts as well.

# Migration recipe

## Changes for #261

The first change can be easily taken care of by the following gofmt+goimports invocations:

$ gofmt -w -r 'draw.Rectangle -> vg.Rectangle' ./mypackage

$ gofmt -w -r 'draw.Point -> vg.Point' ./mypackage

$ goimports -w ./mypackage

## Changes for #266

The second change is a bit trickier but can be tackled with 'golang.org/x/tools/cmd/eg'

the gist of the API change is:

===

type Canvas interface {

    // Translate applies a translational transform

    // to the context.

-   Translate(x, y Length)

+   Translate(pt Point)

    // Scale applies a scaling transform to the

    // context.

 @@ -73,7 +73,7 @@ type Canvas interface {

    // FillString fills in text at the specified

    // location using the given font.

-   FillString(f Font, x, y Length, text string)

+   FillString(f Font, pt Point, text string)

}

// ...

@@ -147,11 +146,11 @@ type PathComp struct {

    // be meaningless.

    Type int

-   // The X and Y fields are used as the destination

-   // of a MoveComp or LineComp and are the center

-   // point of an ArcComp.  They are not used in

+   // The Pos field is used as the destination

+   // of a MoveComp or LineComp and is the center

+   // point of an ArcComp.  It is not used in

    // the CloseComp.

-   X, Y Length

+   Pos Point

===

- before migrating to the new gonum/plot API, change your call sites of vg.Canvas.Translate(x,y) to: somepkg.TranslateOld(c,x,y) (where somepkg.Translate would just forward to vg.Canvas.Translate).

this can be done by the following eg template:

===

package P

import "github.com/gonum/plot/vg"

import "somepkg"

func before(c vg.Canvas, x, y vg.Length) { c.Translate(x, y) }

func after(c vg.Canvas, x, y vg.Length)  { somepkg.Translate(c, x, y) }

===

$ eg -t ./eg-template-translate-step1.go [my-package...]

now, update your gonum/plot to the new API, update somepkg.Translate accordingly, and apply the following eg-template:

===

package P

import "github.com/gonum/plot/vg"

import "somepkg"

func before(c vg.Canvas, x, y vg.Length) { somepkg.Translate(c, x, y) }

func after(c vg.Canvas, x, y vg.Length)  { c.Translate(vg.Point{X: x, Y: y}) }

===

$ eg -t eg-template-translate-step2.go [my-packages...]

similarly for vg.Canvas.FillString.

The vg.PathComp change shouldn't be (much) visible to regular gonum/plot users (except for plotter implementers.)

## Changes for #256

The 3rd change is only relevant for vg.Canvas implementors.

a search on godoc.org didn't reveal any (except for github.com/go-hep/hplot/vgshiny).

in any case, vg.Canvas implementations would need to implement a new method 'DrawImage' method:

 package vg

 type Canvas interface {

   // ...

   DrawImage(rect Rectangle, img image.Image)

 }

get in touch if you need help on any of these aspects.

hth,

-s

[Seb Binet]

FYI, the 3 PRs have been LGTM'ed and I plan to merge them by the middle of the week.

-s

[Seb Binet]

On Mon, Apr 18, 2016 at 12:46 PM, Seb Binet <seb....@gmail.com> wrote:

FYI, the 3 PRs have been LGTM'ed and I plan to merge them by the middle of the week.

done.

-s