diagrams-lib-1.1.0.3: Embedded domain-specific language for declarative graphics

Diagrams.Transform

Description

Affine transformations, parameterized by any vector space. For transformations on particular vector spaces, see e.g. Diagrams.TwoD.Transform.

Synopsis

Transformations

data Transformation v

General (affine) transformations, represented by an invertible linear map, its transpose, and a vector representing a translation component.

By the transpose of a linear map we mean simply the linear map corresponding to the transpose of the map's matrix representation. For example, any scale is its own transpose, since scales are represented by matrices with zeros everywhere except the diagonal. The transpose of a rotation is the same as its inverse.

The reason we need to keep track of transposes is because it turns out that when transforming a shape according to some linear map L, the shape's normal vectors transform according to L's inverse transpose. This is exactly what we need when transforming bounding functions, which are defined in terms of perpendicular (i.e. normal) hyperplanes.

For more general, non-invertable transformations, see `Diagrams.Deform` (in `diagrams-lib`).

Instances

 HasLinearMap v => Semigroup (Transformation v) Transformations are closed under composition; `t1 t2` is the transformation which performs first `t2`, then `t1`. HasLinearMap v => Monoid (Transformation v) HasLinearMap v => Transformable (Transformation v) HasLinearMap v => HasOrigin (Transformation v) (HasLinearMap v, ~ * v (V a), Transformable a) => Action (Transformation v) a Transformations can act on transformable things.

inv :: HasLinearMap v => Transformation v -> Transformation v

Invert a transformation.

transl :: Transformation v -> v

Get the translational component of a transformation.

apply :: HasLinearMap v => Transformation v -> v -> v

Apply a transformation to a vector. Note that any translational component of the transformation will not affect the vector, since vectors are invariant under translation.

papply :: HasLinearMap v => Transformation v -> Point v -> Point v

Apply a transformation to a point.

The Transformable class

class HasLinearMap (V t) => Transformable t where

Type class for things `t` which can be transformed.

Methods

transform :: Transformation (V t) -> t -> t

Apply a transformation to an object.

Instances

 Transformable Double Transformable Rational Transformable R2 Transformable R3 Transformable Ellipsoid Transformable ParallelLight Transformable PointLight Transformable Clip Transformable Image Transformable Text Transformable t => Transformable [t] Transformable a => Transformable (Active a) (Transformable t, Ord t) => Transformable (Set t) HasLinearMap v => Transformable (NullPrim v) (HasLinearMap v, InnerSpace v, Floating (Scalar v)) => Transformable (Envelope v) HasLinearMap v => Transformable (Trace v) HasLinearMap v => Transformable (Attribute v) HasLinearMap v => Transformable (Style v) HasLinearMap v => Transformable (Transformation v) Transformable t => Transformable (TransInv t) HasLinearMap v => Transformable (Point v) Transformable m => Transformable (Deletable m) Transformable (Camera l) (~ * (V t) R2, Transformable t) => Transformable (ScaleInv t) Transformable a => Transformable (Located a) Applying a transformation `t` to a `Located a` results in the transformation being applied to the location, and the linear portion of `t` being applied to the value of type `a` (i.e. it is not translated). HasLinearMap v => Transformable (FixedSegment v) (HasLinearMap v, InnerSpace v, OrderedField (Scalar v)) => Transformable (Trail v) (HasLinearMap v, InnerSpace v, OrderedField (Scalar v)) => Transformable (SegTree v) (HasLinearMap v, InnerSpace v, OrderedField (Scalar v)) => Transformable (Path v) (HasBasis (V b), HasTrie (Basis (V b)), Transformable a, Transformable b, ~ * (V b) (V a)) => Transformable (a -> b) (Transformable a, Transformable b, ~ * (V a) (V b)) => Transformable (a, b) Transformable t => Transformable (Map k t) HasLinearMap v => Transformable (Prim b v) The `Transformable` instance for `Prim` just pushes calls to `transform` down through the `Prim` constructor. HasLinearMap v => Transformable (Query v m) (HasLinearMap (V a), InnerSpace (V a), OrderedField (Scalar (V a)), Measured m a, Transformable a) => Transformable (FingerTree m a) HasLinearMap v => Transformable (Segment c v) HasLinearMap v => Transformable (Offset c v) (HasLinearMap v, InnerSpace v, OrderedField (Scalar v)) => Transformable (Trail' l v) (Transformable a, Transformable b, Transformable c, ~ * (V a) (V b), ~ * (V a) (V c)) => Transformable (a, b, c) (HasLinearMap v, OrderedField (Scalar v), InnerSpace v, Semigroup m) => Transformable (QDiagram b v m) Diagrams can be transformed by transforming each of their components appropriately. (HasLinearMap v, InnerSpace v, Floating (Scalar v)) => Transformable (Subdiagram b v m) (InnerSpace v, Floating (Scalar v), HasLinearMap v) => Transformable (SubMap b v m)

Some specific transformations

translation :: HasLinearMap v => v -> Transformation v

Create a translation.

translate :: (Transformable t, HasLinearMap (V t)) => V t -> t -> t

Translate by a vector.

moveTo :: HasOrigin t => Point (V t) -> t -> t

Translate the object by the translation that sends the origin to the given point. Note that this is dual to `moveOriginTo`, i.e. we should have

```   moveTo (origin .^+ v) === moveOriginTo (origin .^- v)
```

For types which are also `Transformable`, this is essentially the same as `translate`, i.e.

```   moveTo (origin .^+ v) === translate v
```

place :: HasOrigin t => t -> Point (V t) -> t

A flipped variant of `moveTo`, provided for convenience. Useful when writing a function which takes a point as an argument, such as when using `withName` and friends.

scaling :: (HasLinearMap v, Fractional (Scalar v)) => Scalar v -> Transformation v

Create a uniform scaling transformation.

scale :: (Transformable t, Fractional (Scalar (V t)), Eq (Scalar (V t))) => Scalar (V t) -> t -> t

Scale uniformly in every dimension by the given scalar.

Miscellaneous transformation-related utilities

Conjugate one transformation by another. `conjugate t1 t2` is the transformation which performs first `t1`, then `t2`, then the inverse of `t1`.

under :: Transformable a => (a -> a) -> Transformation (V a) -> a -> aSource

Carry out some transformation "under" another one: ```f `under` t``` first applies `t`, then `f`, then the inverse of `t`. For example, `scaleX 2 `under` rotation (-1/8 @@ Turn)` is the transformation which scales by a factor of 2 along the diagonal line y = x.

Note that

```   (transform t2) `under` t1 == transform (conjugate t1 t2)
```

for all transformations `t1` and `t2`.

The HasOrigin class

class VectorSpace (V t) => HasOrigin t where

Class of types which have an intrinsic notion of a "local origin", i.e. things which are not invariant under translation, and which allow the origin to be moved.

One might wonder why not just use `Transformable` instead of having a separate class for `HasOrigin`; indeed, for types which are instances of both we should have the identity

```   moveOriginTo (origin .^+ v) === translate (negateV v)
```

The reason is that some things (e.g. vectors, `Trail`s) are transformable but are translationally invariant, i.e. have no origin.

Methods

moveOriginTo :: Point (V t) -> t -> t

Move the local origin to another point.

Note that this function is in some sense dual to `translate` (for types which are also `Transformable`); moving the origin itself while leaving the object "fixed" is dual to fixing the origin and translating the diagram.

Instances

 HasOrigin Image HasOrigin Text HasOrigin a => HasOrigin [a] HasOrigin a => HasOrigin (Active a) (HasOrigin a, Ord a) => HasOrigin (Set a) (InnerSpace v, Fractional (Scalar v)) => HasOrigin (Envelope v) The local origin of an envelope is the point with respect to which bounding queries are made, i.e. the point from which the input vectors are taken to originate. VectorSpace v => HasOrigin (Trace v) HasLinearMap v => HasOrigin (Transformation v) VectorSpace (V t) => HasOrigin (TransInv t) VectorSpace v => HasOrigin (Point v) (VectorSpace v, HasBasis v, Ord (Basis v), AdditiveGroup (Scalar v), Ord (Scalar v)) => HasOrigin (BoundingBox v) (~ * (V t) R2, HasOrigin t) => HasOrigin (ScaleInv t) VectorSpace (V a) => HasOrigin (Located a) `Located a` is an instance of `HasOrigin` whether `a` is or not. In particular, translating a `Located a` simply translates the associated point (and does not affect the value of type `a`). VectorSpace v => HasOrigin (FixedSegment v) VectorSpace v => HasOrigin (Path v) (HasOrigin a, HasOrigin b, ~ * (V a) (V b)) => HasOrigin (a, b) HasOrigin a => HasOrigin (Map k a) VectorSpace v => HasOrigin (Query v m) (HasLinearMap v, InnerSpace v, OrderedField (Scalar v), Semigroup m) => HasOrigin (QDiagram b v m) Every diagram has an intrinsic "local origin" which is the basis for all combining operations. (HasLinearMap v, InnerSpace v, OrderedField (Scalar v)) => HasOrigin (Subdiagram b v m) (OrderedField (Scalar v), InnerSpace v, HasLinearMap v) => HasOrigin (SubMap b v m)

moveOriginBy :: HasOrigin t => V t -> t -> t

Move the local origin by a relative vector.