diagrams-lib-1.4.2.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 :: Type -> Type) n #

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. (For a more detailed explanation and proof, see https://wiki.haskell.org/Diagrams/Dev/Transformations.) 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-invertible transformations, see Diagrams.Deform (in diagrams-lib).

Instances
 (Additive v, Num n) => Semigroup (Transformation v n) Transformations are closed under composition; t1 <> t2 is the transformation which performs first t2, then t1. Instance detailsDefined in Diagrams.Core.Transform Methods(<>) :: Transformation v n -> Transformation v n -> Transformation v n #sconcat :: NonEmpty (Transformation v n) -> Transformation v n #stimes :: Integral b => b -> Transformation v n -> Transformation v n # (Additive v, Num n) => Monoid (Transformation v n) Instance detailsDefined in Diagrams.Core.Transform Methodsmappend :: Transformation v n -> Transformation v n -> Transformation v n #mconcat :: [Transformation v n] -> Transformation v n # (Additive v, Num n) => Transformable (Transformation v n) Instance detailsDefined in Diagrams.Core.Transform Methodstransform :: Transformation (V (Transformation v n)) (N (Transformation v n)) -> Transformation v n -> Transformation v n # (Additive v, Num n) => HasOrigin (Transformation v n) Instance detailsDefined in Diagrams.Core.Transform MethodsmoveOriginTo :: Point (V (Transformation v n)) (N (Transformation v n)) -> Transformation v n -> Transformation v n # (Transformable a, V a ~ v, N a ~ n) => Action (Transformation v n) a Transformations can act on transformable things. Instance detailsDefined in Diagrams.Core.Transform Methodsact :: Transformation v n -> a -> a # type V (Transformation v n) Instance detailsDefined in Diagrams.Core.Transform type V (Transformation v n) = v type N (Transformation v n) Instance detailsDefined in Diagrams.Core.Transform type N (Transformation v n) = n

inv :: (Functor v, Num n) => Transformation v n -> Transformation v n #

Invert a transformation.

transl :: Transformation v n -> v n #

Get the translational component of a transformation.

apply :: Transformation v n -> v n -> v n #

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 :: (Additive v, Num n) => Transformation v n -> Point v n -> Point v n #

Apply a transformation to a point.

# The Transformable class

class Transformable t where #

Type class for things t which can be transformed.

Methods

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

Apply a transformation to an object.

Instances
 Transformable t => Transformable [t] Instance detailsDefined in Diagrams.Core.Transform Methodstransform :: Transformation (V [t]) (N [t]) -> [t] -> [t] # # Instance detailsDefined in Diagrams.Animation.Active Methodstransform :: Transformation (V (Active a)) (N (Active a)) -> Active a -> Active a # (Transformable t, Ord t) => Transformable (Set t) Instance detailsDefined in Diagrams.Core.Transform Methodstransform :: Transformation (V (Set t)) (N (Set t)) -> Set t -> Set t # (Num (N t), Additive (V t), Transformable t) => Transformable (TransInv t) Instance detailsDefined in Diagrams.Core.Transform Methodstransform :: Transformation (V (TransInv t)) (N (TransInv t)) -> TransInv t -> TransInv t # # Instance detailsDefined in Diagrams.ThreeD.Types Methodstransform :: Transformation (V (V3 n)) (N (V3 n)) -> V3 n -> V3 n # # Instance detailsDefined in Diagrams.TwoD.Types Methodstransform :: Transformation (V (V2 n)) (N (V2 n)) -> V2 n -> V2 n # Instance detailsDefined in Diagrams.Core.Transform Methodstransform :: Transformation (V (Deletable m)) (N (Deletable m)) -> Deletable m -> Deletable m # # Instance detailsDefined in Diagrams.ThreeD.Light Methodstransform :: Transformation (V (ParallelLight n)) (N (ParallelLight n)) -> ParallelLight n -> ParallelLight n # # Instance detailsDefined in Diagrams.ThreeD.Light Methodstransform :: Transformation (V (PointLight n)) (N (PointLight n)) -> PointLight n -> PointLight n # (V t ~ V2, N t ~ n, RealFloat n, Transformable t) => Transformable (ScaleInv t) # Instance detailsDefined in Diagrams.Transform.ScaleInv Methodstransform :: Transformation (V (ScaleInv t)) (N (ScaleInv t)) -> ScaleInv t -> ScaleInv t # Fractional n => Transformable (CSG n) # Instance detailsDefined in Diagrams.ThreeD.Shapes Methodstransform :: Transformation (V (CSG n)) (N (CSG n)) -> CSG n -> CSG n # # Instance detailsDefined in Diagrams.ThreeD.Shapes Methodstransform :: Transformation (V (Frustum n)) (N (Frustum n)) -> Frustum n -> Frustum n # Fractional n => Transformable (Box n) # Instance detailsDefined in Diagrams.ThreeD.Shapes Methodstransform :: Transformation (V (Box n)) (N (Box n)) -> Box n -> Box n # # Instance detailsDefined in Diagrams.ThreeD.Shapes Methodstransform :: Transformation (V (Ellipsoid n)) (N (Ellipsoid n)) -> Ellipsoid n -> Ellipsoid n # (Additive (V a), Num (N a), 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). Instance detailsDefined in Diagrams.Located Methodstransform :: Transformation (V (Located a)) (N (Located a)) -> Located a -> Located a # # Instance detailsDefined in Diagrams.TwoD.Path Methodstransform :: Transformation (V (Clip n)) (N (Clip n)) -> Clip n -> Clip n # # Instance detailsDefined in Diagrams.TwoD.Attributes Methodstransform :: Transformation (V (LGradient n)) (N (LGradient n)) -> LGradient n -> LGradient n # # Instance detailsDefined in Diagrams.TwoD.Attributes Methodstransform :: Transformation (V (RGradient n)) (N (RGradient n)) -> RGradient n -> RGradient n # Floating n => Transformable (Texture n) # Instance detailsDefined in Diagrams.TwoD.Attributes Methodstransform :: Transformation (V (Texture n)) (N (Texture n)) -> Texture n -> Texture n # # Instance detailsDefined in Diagrams.TwoD.Attributes Methodstransform :: Transformation (V (FillTexture n)) (N (FillTexture n)) -> FillTexture n -> FillTexture n # # Instance detailsDefined in Diagrams.TwoD.Attributes Methodstransform :: Transformation (V (LineTexture n)) (N (LineTexture n)) -> LineTexture n -> LineTexture n # Floating n => Transformable (Text n) # Instance detailsDefined in Diagrams.TwoD.Text Methodstransform :: Transformation (V (Text n)) (N (Text n)) -> Text n -> Text n # (V t ~ v, N t ~ n, V t ~ V s, N t ~ N s, Functor v, Num n, Transformable t, Transformable s) => Transformable (s -> t) Instance detailsDefined in Diagrams.Core.Transform Methodstransform :: Transformation (V (s -> t)) (N (s -> t)) -> (s -> t) -> s -> t # (Transformable t, Transformable s, V t ~ V s, N t ~ N s) => Transformable (t, s) Instance detailsDefined in Diagrams.Core.Transform Methodstransform :: Transformation (V (t, s)) (N (t, s)) -> (t, s) -> (t, s) # Transformable t => Transformable (Map k t) Instance detailsDefined in Diagrams.Core.Transform Methodstransform :: Transformation (V (Map k t)) (N (Map k t)) -> Map k t -> Map k t # (Metric v, Floating n) => Transformable (Envelope v n) Instance detailsDefined in Diagrams.Core.Envelope Methodstransform :: Transformation (V (Envelope v n)) (N (Envelope v n)) -> Envelope v n -> Envelope v n # (Additive v, Num n) => Transformable (Trace v n) Instance detailsDefined in Diagrams.Core.Trace Methodstransform :: Transformation (V (Trace v n)) (N (Trace v n)) -> Trace v n -> Trace v n # (Additive v, Traversable v, Floating n) => Transformable (Attribute v n) TAttributes are transformed directly, MAttributes have their local scale multiplied by the average scale of the transform. Plain Attributes are unaffected. Instance detailsDefined in Diagrams.Core.Style Methodstransform :: Transformation (V (Attribute v n)) (N (Attribute v n)) -> Attribute v n -> Attribute v n # (Additive v, Traversable v, Floating n) => Transformable (Style v n) Instance detailsDefined in Diagrams.Core.Style Methodstransform :: Transformation (V (Style v n)) (N (Style v n)) -> Style v n -> Style v n # (Additive v, Num n) => Transformable (Transformation v n) Instance detailsDefined in Diagrams.Core.Transform Methodstransform :: Transformation (V (Transformation v n)) (N (Transformation v n)) -> Transformation v n -> Transformation v n # (InSpace v n t, Transformable t, HasLinearMap v, Floating n) => Transformable (Measured n t) Instance detailsDefined in Diagrams.Core.Transform Methodstransform :: Transformation (V (Measured n t)) (N (Measured n t)) -> Measured n t -> Measured n t # (Additive v, Num n) => Transformable (Point v n) Instance detailsDefined in Diagrams.Core.Transform Methodstransform :: Transformation (V (Point v n)) (N (Point v n)) -> Point v n -> Point v n # (Measured m a, Transformable a) => Transformable (FingerTree m a) # Instance detailsDefined in Diagrams.Trail Methodstransform :: Transformation (V (FingerTree m a)) (N (FingerTree m a)) -> FingerTree m a -> FingerTree m a # (V (v n) ~ v, N (v n) ~ n, Transformable (v n)) => Transformable (Direction v n) # Instance detailsDefined in Diagrams.Direction Methodstransform :: Transformation (V (Direction v n)) (N (Direction v n)) -> Direction v n -> Direction v n # Num n => Transformable (Camera l n) # Instance detailsDefined in Diagrams.ThreeD.Camera Methodstransform :: Transformation (V (Camera l n)) (N (Camera l n)) -> Camera l n -> Camera l n # (Additive v, Num n) => Transformable (FixedSegment v n) # Instance detailsDefined in Diagrams.Segment Methodstransform :: Transformation (V (FixedSegment v n)) (N (FixedSegment v n)) -> FixedSegment v n -> FixedSegment v n # (HasLinearMap v, Metric v, OrderedField n) => Transformable (Trail v n) # Instance detailsDefined in Diagrams.Trail Methodstransform :: Transformation (V (Trail v n)) (N (Trail v n)) -> Trail v n -> Trail v n # (Floating n, Ord n, Metric v) => Transformable (SegTree v n) # Instance detailsDefined in Diagrams.Trail Methodstransform :: Transformation (V (SegTree v n)) (N (SegTree v n)) -> SegTree v n -> SegTree v n # (HasLinearMap v, Metric v, OrderedField n) => Transformable (Path v n) # Instance detailsDefined in Diagrams.Path Methodstransform :: Transformation (V (Path v n)) (N (Path v n)) -> Path v n -> Path v n # Fractional n => Transformable (DImage n a) # Instance detailsDefined in Diagrams.TwoD.Image Methodstransform :: Transformation (V (DImage n a)) (N (DImage n a)) -> DImage n a -> DImage n a # (Transformable t, Transformable s, Transformable u, V s ~ V t, N s ~ N t, V s ~ V u, N s ~ N u) => Transformable (t, s, u) Instance detailsDefined in Diagrams.Core.Transform Methodstransform :: Transformation (V (t, s, u)) (N (t, s, u)) -> (t, s, u) -> (t, s, u) # Transformable (Prim b v n) The Transformable instance for Prim just pushes calls to transform down through the Prim constructor. Instance detailsDefined in Diagrams.Core.Types Methodstransform :: Transformation (V (Prim b v n)) (N (Prim b v n)) -> Prim b v n -> Prim b v n # (Additive v, Num n) => Transformable (Query v n m) Instance detailsDefined in Diagrams.Core.Query Methodstransform :: Transformation (V (Query v n m)) (N (Query v n m)) -> Query v n m -> Query v n m # Transformable (Segment c v n) # Instance detailsDefined in Diagrams.Segment Methodstransform :: Transformation (V (Segment c v n)) (N (Segment c v n)) -> Segment c v n -> Segment c v n # Transformable (Offset c v n) # Instance detailsDefined in Diagrams.Segment Methodstransform :: Transformation (V (Offset c v n)) (N (Offset c v n)) -> Offset c v n -> Offset c v n # (HasLinearMap v, Metric v, OrderedField n) => Transformable (Trail' l v n) # Instance detailsDefined in Diagrams.Trail Methodstransform :: Transformation (V (Trail' l v n)) (N (Trail' l v n)) -> Trail' l v n -> Trail' l v n # (OrderedField n, Metric v, Semigroup m) => Transformable (QDiagram b v n m) Diagrams can be transformed by transforming each of their components appropriately. Instance detailsDefined in Diagrams.Core.Types Methodstransform :: Transformation (V (QDiagram b v n m)) (N (QDiagram b v n m)) -> QDiagram b v n m -> QDiagram b v n m # Transformable (Subdiagram b v n m) Instance detailsDefined in Diagrams.Core.Types Methodstransform :: Transformation (V (Subdiagram b v n m)) (N (Subdiagram b v n m)) -> Subdiagram b v n m -> Subdiagram b v n m # Transformable (SubMap b v n m) Instance detailsDefined in Diagrams.Core.Types Methodstransform :: Transformation (V (SubMap b v n m)) (N (SubMap b v n m)) -> SubMap b v n m -> SubMap b v n m #

# Some specific transformations

translation :: v n -> Transformation v n #

Create a translation.

translate :: Transformable t => Vn t -> t -> t #

Translate by a vector.

moveTo :: (InSpace v n t, HasOrigin t) => Point v n -> 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 :: (InSpace v n t, HasOrigin t) => t -> Point v n -> 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 :: (Additive v, Fractional n) => n -> Transformation v n #

Create a uniform scaling transformation.

scale :: (InSpace v n a, Eq n, Fractional n, Transformable a) => n -> a -> a #

Scale uniformly in every dimension by the given scalar.

# Miscellaneous transformation-related utilities

conjugate :: (Additive v, Num n) => Transformation v n -> Transformation v n -> Transformation v n #

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

underT :: (InSpace v n a, SameSpace a b, Transformable a, Transformable b) => (a -> b) -> Transformation v n -> a -> b #

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

Note that

(transform t2) underT t1 == transform (conjugate t1 t2)


for all transformations t1 and t2.

See also the isomorphisms like transformed, movedTo, movedFrom, and translated.

transformed :: (InSpace v n a, SameSpace a b, Transformable a, Transformable b) => Transformation v n -> Iso a b a b #

Use a Transformation to make an Iso between an object transformed and untransformed. This is useful for carrying out functions under another transform:

under (transformed t) f               == transform (inv t) . f . transform t
under (transformed t1) (transform t2) == transform (conjugate t1 t2)
transformed t ## a                    == transform t a
a ^. transformed t                    == transform (inv t) a


translated :: (InSpace v n a, SameSpace a b, Transformable a, Transformable b) => v n -> Iso a b a b #

Use a vector to make an Iso between an object translated and untranslated.

under (translated v) f == translate (-v) . f . translate v
translated v ## a      == translate v a
a ^. translated v      == translate (-v) a
over (translated v) f  == translate v . f . translate (-v)


movedTo :: (InSpace v n a, SameSpace a b, HasOrigin a, HasOrigin b) => Point v n -> Iso a b a b #

Use a Point to make an Iso between an object moved to and from that point:

under (movedTo p) f == moveTo (-p) . f . moveTo p
over (movedTo p) f  == moveTo p . f . moveTo (-p)
movedTo p           == from (movedFrom p)
movedTo p ## a      == moveTo p a
a ^. movedTo p      == moveOriginTo p a


movedFrom :: (InSpace v n a, SameSpace a b, HasOrigin a, HasOrigin b) => Point v n -> Iso a b a b #

Use a Transformation to make an Iso between an object transformed and untransformed. We have

under (movedFrom p) f == moveTo p . f . moveTo (-p)
movedFrom p           == from (movedTo p)
movedFrom p ## a      == moveOriginTo p a
a ^. movedFrom p      == moveTo p a
over (movedFrom p) f  == moveTo (-p) . f . moveTo p


# The HasOrigin class

class 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 (negated v)


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

Methods

moveOriginTo :: Point (V t) (N 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 t => HasOrigin [t] Instance detailsDefined in Diagrams.Core.HasOrigin MethodsmoveOriginTo :: Point (V [t]) (N [t]) -> [t] -> [t] # HasOrigin a => HasOrigin (Active a) # Instance detailsDefined in Diagrams.Animation.Active MethodsmoveOriginTo :: Point (V (Active a)) (N (Active a)) -> Active a -> Active a # (HasOrigin t, Ord t) => HasOrigin (Set t) Instance detailsDefined in Diagrams.Core.HasOrigin MethodsmoveOriginTo :: Point (V (Set t)) (N (Set t)) -> Set t -> Set t # Instance detailsDefined in Diagrams.Core.Transform MethodsmoveOriginTo :: Point (V (TransInv t)) (N (TransInv t)) -> TransInv t -> TransInv t # (V t ~ v, N t ~ n, Additive v, Num n, HasOrigin t) => HasOrigin (ScaleInv t) # Instance detailsDefined in Diagrams.Transform.ScaleInv MethodsmoveOriginTo :: Point (V (ScaleInv t)) (N (ScaleInv t)) -> ScaleInv t -> ScaleInv t # (Num (N a), Additive (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). Instance detailsDefined in Diagrams.Located MethodsmoveOriginTo :: Point (V (Located a)) (N (Located a)) -> Located a -> Located a # Floating n => HasOrigin (Text n) # Instance detailsDefined in Diagrams.TwoD.Text MethodsmoveOriginTo :: Point (V (Text n)) (N (Text n)) -> Text n -> Text n # (HasOrigin t, HasOrigin s, SameSpace s t) => HasOrigin (s, t) Instance detailsDefined in Diagrams.Core.HasOrigin MethodsmoveOriginTo :: Point (V (s, t)) (N (s, t)) -> (s, t) -> (s, t) # HasOrigin t => HasOrigin (Map k t) Instance detailsDefined in Diagrams.Core.HasOrigin MethodsmoveOriginTo :: Point (V (Map k t)) (N (Map k t)) -> Map k t -> Map k t # (Metric v, Fractional n) => HasOrigin (Envelope v n) 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. Instance detailsDefined in Diagrams.Core.Envelope MethodsmoveOriginTo :: Point (V (Envelope v n)) (N (Envelope v n)) -> Envelope v n -> Envelope v n # (Additive v, Num n) => HasOrigin (Trace v n) Instance detailsDefined in Diagrams.Core.Trace MethodsmoveOriginTo :: Point (V (Trace v n)) (N (Trace v n)) -> Trace v n -> Trace v n # (Additive v, Num n) => HasOrigin (Transformation v n) Instance detailsDefined in Diagrams.Core.Transform MethodsmoveOriginTo :: Point (V (Transformation v n)) (N (Transformation v n)) -> Transformation v n -> Transformation v n # HasOrigin t => HasOrigin (Measured n t) Instance detailsDefined in Diagrams.Core.HasOrigin MethodsmoveOriginTo :: Point (V (Measured n t)) (N (Measured n t)) -> Measured n t -> Measured n t # (Additive v, Num n) => HasOrigin (Point v n) Instance detailsDefined in Diagrams.Core.HasOrigin MethodsmoveOriginTo :: Point (V (Point v n)) (N (Point v n)) -> Point v n -> Point v n # (Additive v, Num n) => HasOrigin (FixedSegment v n) # Instance detailsDefined in Diagrams.Segment MethodsmoveOriginTo :: Point (V (FixedSegment v n)) (N (FixedSegment v n)) -> FixedSegment v n -> FixedSegment v n # (Additive v, Num n) => HasOrigin (Path v n) # Instance detailsDefined in Diagrams.Path MethodsmoveOriginTo :: Point (V (Path v n)) (N (Path v n)) -> Path v n -> Path v n # Fractional n => HasOrigin (DImage n a) # Instance detailsDefined in Diagrams.TwoD.Image MethodsmoveOriginTo :: Point (V (DImage n a)) (N (DImage n a)) -> DImage n a -> DImage n a # (Additive v, Num n) => HasOrigin (BoundingBox v n) # Instance detailsDefined in Diagrams.BoundingBox MethodsmoveOriginTo :: Point (V (BoundingBox v n)) (N (BoundingBox v n)) -> BoundingBox v n -> BoundingBox v n # (Additive v, Num n) => HasOrigin (Query v n m) Instance detailsDefined in Diagrams.Core.Query MethodsmoveOriginTo :: Point (V (Query v n m)) (N (Query v n m)) -> Query v n m -> Query v n m # (Metric v, OrderedField n, Semigroup m) => HasOrigin (QDiagram b v n m) Every diagram has an intrinsic "local origin" which is the basis for all combining operations. Instance detailsDefined in Diagrams.Core.Types MethodsmoveOriginTo :: Point (V (QDiagram b v n m)) (N (QDiagram b v n m)) -> QDiagram b v n m -> QDiagram b v n m # (Metric v, OrderedField n) => HasOrigin (Subdiagram b v n m) Instance detailsDefined in Diagrams.Core.Types MethodsmoveOriginTo :: Point (V (Subdiagram b v n m)) (N (Subdiagram b v n m)) -> Subdiagram b v n m -> Subdiagram b v n m # (OrderedField n, Metric v) => HasOrigin (SubMap b v n m) Instance detailsDefined in Diagrams.Core.Types MethodsmoveOriginTo :: Point (V (SubMap b v n m)) (N (SubMap b v n m)) -> SubMap b v n m -> SubMap b v n m #

moveOriginBy :: (V t ~ v, N t ~ n, HasOrigin t) => v n -> t -> t #

Move the local origin by a relative vector.