├── .github └── FUNDING.yml ├── .gitignore ├── Cargo.toml ├── LICENSE ├── README.md ├── images └── car.png └── src └── lib.rs /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | # These are supported funding model platforms 2 | 3 | github: bvssvni 4 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /target/ 2 | **/*.rs.bk 3 | Cargo.lock 4 | -------------------------------------------------------------------------------- /Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | name = "piston3d-construct" 3 | version = "0.1.0" 4 | authors = ["Sven Nilsen "] 5 | description = "A library for higher order functional programming with homotopy maps to construct 3D geometry" 6 | readme = "README.md" 7 | documentation = "https://docs.rs/piston3d-construct" 8 | repository = "https://github.com/PistonDevelopers/construct.git" 9 | webpage = "https://github.com/PistonDevelopers/construct" 10 | license = "MIT" 11 | exclude = [ 12 | "images/*" 13 | ] 14 | 15 | [lib] 16 | name = "construct" 17 | path = "src/lib.rs" 18 | 19 | [dependencies] 20 | vecmath = "0.3.0" 21 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2017 PistonDevelopers 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # construct 2 | A library for higher order functional programming with homotopy maps to construct 3D geometry 3 | 4 | ![car](./images/car.png) 5 | 6 | ### What is a homotopy map? 7 | 8 | A [homotopy](https://en.wikipedia.org/wiki/Homotopy) is a continuous deformation between two functions. Think about combining two functions `f` and `g` with a parameter in the range between 0 and 1 such that setting the parameter to 0 gives you `f` and setting it to 1 gives you `g`. With other words, it lets you interpolate smoothly between functions. 9 | 10 | This library uses a simplified homotopy version designed for constructing 3D geometry: 11 | 12 | ```rust 13 | /// A function of type `1d -> 3d`. 14 | pub type Fn1 = Arc [T; 3] + Sync + Send>; 15 | /// A function of type `2d -> 3d`. 16 | pub type Fn2 = Arc [T; 3] + Sync + Send>; 17 | /// A function of type `3d -> 3d`. 18 | pub type Fn3 = Arc [T; 3] + Sync + Send>; 19 | ``` 20 | 21 | In this library, these functions are called *homotopy maps* and usually satisfies these properties: 22 | 23 | - All inputs are assumed to be normalized, starting at 0 and ending at 1. This means that `Fn1` forms a curved line, `Fn2` forms a curved quad, and `Fn3` forms a curved cube. 24 | - The `Arc` smart pointer makes it possible to clone closures. 25 | - The `Sync` and `Send` constraints makes it easier to program with multiple threads. 26 | - Basic geometric shapes are continuous within the range from 0 to 1. 27 | 28 | A curved cube does not mean it need to look like a cube. Actually, you can create a variety of shapes that do not look like cubes at all, e.g. a sphere. What is meant by a "curved cube" is that there are 3 parameters between 0 and 1 controlling the generation of points. If you used an identity map, you would get a cube shape. The transformation to other shapes is the reason it is called a "curved cube". 29 | 30 | ### Motivation 31 | 32 | Constructing 3D geometry is an iterative process where the final design/need can be quite different from the first draft. In game engines there are additional needs like generating multiple models of various detail or adjusting models depending on the capacity of the target platform. This makes it desirable to have some tools where one can work with an idea without getting slowed down by a lot of technical details. 33 | 34 | Homotopy maps have the property that the geometry can be constructed by need, without any additional instructions. This makes it a suitable candidate for combining them with higher order functional programming. Functions give an accurate representation while at the same time being lazy, such that one can e.g. intersect a curved cube to get a curved quad. 35 | 36 | This library is an experiment to see how homotopy maps and higher order functional programming can be used to iterate on design. Function names are very short to provide good ergonomics. 37 | -------------------------------------------------------------------------------- /images/car.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/PistonDevelopers/construct/bea9fe6820927e40d4bdaa8e154f25a808bce718/images/car.png -------------------------------------------------------------------------------- /src/lib.rs: -------------------------------------------------------------------------------- 1 | #![deny(missing_docs)] 2 | 3 | //! A library for higher order functional programming with homotopy maps to construct 3D geometry. 4 | //! 5 | //! ### What is a homotopy map? 6 | //! 7 | //! A [homotopy](https://en.wikipedia.org/wiki/Homotopy) is a continuous 8 | //! deformation between two functions. 9 | //! Think about combining two functions `f` and `g` with a parameter in the range 10 | //! between 0 and 1 such that setting the parameter to 0 gives you `f` and 11 | //! setting it to 1 gives you `g`. 12 | //! With other words, it lets you interpolate smoothly between functions. 13 | //! 14 | //! This library uses a simplified homotopy version designed for constructing 3D geometry: 15 | //! 16 | //! ```rust 17 | //! /// A function of type `1d -> 3d`. 18 | //! pub type Fn1 = Arc [T; 3] + Sync + Send>; 19 | //! /// A function of type `2d -> 3d`. 20 | //! pub type Fn2 = Arc [T; 3] + Sync + Send>; 21 | //! /// A function of type `3d -> 3d`. 22 | //! pub type Fn3 = Arc [T; 3] + Sync + Send>; 23 | //! ``` 24 | //! 25 | //! In this library, these functions are called *homotopy maps* and usually 26 | //! satisfies these properties: 27 | //! 28 | //! - All inputs are assumed to be normalized, starting at 0 and ending at 1. 29 | //! This means that `Fn1` forms a curved line, `Fn2` forms a curved quad, 30 | //! and `Fn3` forms a curved cube. 31 | //! - The `Arc` smart pointer makes it possible to clone closures. 32 | //! - The `Sync` and `Send` constraints makes it easier to program with multiple threads. 33 | //! - Basic geometric shapes are continuous within the range from 0 to 1. 34 | //! 35 | //! A curved cube does not mean it need to look like a cube. 36 | //! Actually, you can create a variety of shapes that do not look like cubes at all, 37 | //! e.g. a sphere. 38 | //! What is meant by a "curved cube" is that there are 3 parameters between 0 and 1 39 | //! controlling the generation of points. 40 | //! If you used an identity map, you would get a cube shape. 41 | //! The transformation to other shapes is the reason it is called a "curved cube". 42 | //! 43 | //! ### Motivation 44 | //! 45 | //! Constructing 3D geometry is an iterative process where the final design/need 46 | //! can be quite different from the first draft. 47 | //! In game engines there are additional needs like generating multiple models of various 48 | //! detail or adjusting models depending on the capacity of the target platform. 49 | //! This makes it desirable to have some tools where one can work with an idea without 50 | //! getting slowed down by a lot of technical details. 51 | //! 52 | //! Homotopy maps have the property that the geometry can be constructed by need, 53 | //! without any additional instructions. 54 | //! This makes it a suitable candidate for combining them with higher order functional programming. 55 | //! Functions give an accurate representation while at the same time being lazy, 56 | //! such that one can e.g. intersect a curved cube to get a curved quad. 57 | //! 58 | //! This library is an experiment to see how homotopy maps and higher order functional programming 59 | //! can be used to iterate on design. 60 | //! Function names are very short to provide good ergonomics. 61 | 62 | extern crate vecmath; 63 | 64 | pub use vecmath::vec3_add as add3; 65 | pub use vecmath::vec2_add as add2; 66 | pub use vecmath::vec3_sub as sub3; 67 | pub use vecmath::vec2_sub as sub2; 68 | pub use vecmath::vec3_len as len3; 69 | pub use vecmath::vec2_len as len2; 70 | pub use vecmath::vec3_scale as scale3; 71 | pub use vecmath::vec2_scale as scale2; 72 | pub use vecmath::vec2_cast as cast2; 73 | pub use vecmath::vec3_cast as cast3; 74 | pub use vecmath::traits::*; 75 | 76 | use std::sync::Arc; 77 | 78 | /// A function of type `1d -> 3d`. 79 | pub type Fn1 = Arc [T; 3] + Sync + Send>; 80 | /// A function of type `2d -> 3d`. 81 | pub type Fn2 = Arc [T; 3] + Sync + Send>; 82 | /// A function of type `3d -> 3d`. 83 | pub type Fn3 = Arc [T; 3] + Sync + Send>; 84 | 85 | /// Returns a linear function. 86 | pub fn lin(a: [T; 3], b: [T; 3]) -> Fn1 { 87 | return Arc::new(move |t| add3(a, scale3(sub3(b, a), t))) 88 | } 89 | 90 | /// Creates a linear interpolation between two functions. 91 | pub fn lin2(a: Fn1, b: Fn1) -> Fn1 { 92 | return Arc::new(move |t| { 93 | add3(scale3(a(t), ::one() - t), scale3(b(t), t)) 94 | }) 95 | } 96 | 97 | /// Quadratic bezier curve. 98 | pub fn qbez(a: [T; 3], b: [T; 3], c: [T; 3]) -> Fn1 { 99 | lin2(lin(a, b), lin(b, c)) 100 | } 101 | 102 | /// Cubic bezier curve. 103 | pub fn cbez( 104 | a: [T; 3], 105 | b: [T; 3], 106 | c: [T; 3], 107 | d: [T; 3], 108 | ) -> Fn1 { 109 | lin2(lin(a, b), lin(c, d)) 110 | } 111 | 112 | /// Constructs a curved quad by smoothing between boundary functions. 113 | pub fn cquad( 114 | smooth: T, 115 | ab: Fn1, 116 | cd: Fn1, 117 | ac: Fn1, 118 | bd: Fn1 119 | ) -> Fn2 120 | where f64: Cast 121 | { 122 | let _1: T = One::one(); 123 | let _0: T = Zero::zero(); 124 | let _05: T = 0.5.cast(); 125 | let _4: T = 4.0.cast(); 126 | return Arc::new(move |t| { 127 | let abx = ab(t[1]); 128 | let cdx = cd(t[1]); 129 | let acx = ac(t[0]); 130 | let bdx = bd(t[0]); 131 | 132 | let w0 = _4 * (t[0] - _05) * (t[0] - _05) + smooth; 133 | let w1 = _4 * (t[1] - _05) * (t[1] - _05) + smooth; 134 | // Normalize weights. 135 | let (w0, w1) = (w0 / (w0 + w1), w1 / (w0 + w1)); 136 | 137 | let a = add3(abx, scale3(sub3(cdx, abx), t[0])); 138 | let b = add3(acx, scale3(sub3(bdx, acx), t[1])); 139 | if w0 == _1 {a} 140 | else if w1 == _1 {b} 141 | else if (w0 + w1) == _0 { 142 | scale3(add3(a, b), _05) 143 | } 144 | else { 145 | add3(scale3(a, w0), scale3(b, w1)) 146 | } 147 | }) 148 | } 149 | 150 | /// Concatenates two `1d -> 3d` functions returning a new function. 151 | /// 152 | /// The input to the new function is normalized. 153 | pub fn con(w: T, a: Fn1, b: Fn1) -> Fn1 { 154 | return Arc::new(move |t| { 155 | if t < w {a(t / w)} 156 | else {b((t - w) / (::one() - w))} 157 | }) 158 | } 159 | 160 | /// Concatenates two `2d -> 3d` functions at x-weight. 161 | pub fn conx2(wx: T, a: Fn2, b: Fn2) -> Fn2 { 162 | return Arc::new(move |t| { 163 | if t[0] < wx {a([t[0] / wx, t[1]])} 164 | else {b(([(t[0] - wx) / (::one() - wx), t[1]]))} 165 | }) 166 | } 167 | 168 | /// Concatenates two `2d -> 3d` functions at y-weight. 169 | pub fn cony2(wy: T, a: Fn2, b: Fn2) -> Fn2 { 170 | return Arc::new(move |t| { 171 | if t[1] < wy {a([t[0], t[1] / wy])} 172 | else {b([t[0], (t[1] - wy) / (::one() - wy)])} 173 | }) 174 | } 175 | 176 | /// Concatenates two `3d -> 3d` functions at x-weight. 177 | pub fn conx3(wx: T, a: Fn3, b: Fn3) -> Fn3 { 178 | return Arc::new(move |t| { 179 | if t[0] < wx {a([t[0] / wx, t[1], t[2]])} 180 | else {b(([(t[0] - wx) / (::one() - wx), t[1], t[2]]))} 181 | }) 182 | } 183 | 184 | /// Concates two `3d -> 3d` functions at y-weight. 185 | pub fn cony3(wy: T, a: Fn3, b: Fn3) -> Fn3 { 186 | return Arc::new(move |t| { 187 | if t[1] < wy {a([t[0], t[1] / wy, t[2]])} 188 | else {b([t[0], (t[1] - wy) / (::one() - wy), t[2]])} 189 | }) 190 | } 191 | 192 | /// Concates two `3d -> 3d` functions at z-weight. 193 | pub fn conz3(wz: T, a: Fn3, b: Fn3) -> Fn3 { 194 | return Arc::new(move |t| { 195 | if t[2] < wz {a([t[0], t[1], t[2] / wz])} 196 | else {b([t[0], t[1], (t[2] - wz) / (::one() - wz)])} 197 | }) 198 | } 199 | 200 | /// Mirror shape `1d -> 3d` around yz-plane at x coordinate. 201 | pub fn mx( 202 | x: U, 203 | a: Arc [U; 3] + Sync + Send> 204 | ) -> Arc [U; 3] + Sync + Send> 205 | where f64: Cast 206 | { 207 | return Arc::new(move |t| { 208 | let pos = a(t); 209 | [2.0.cast() * x - pos[0], pos[1], pos[2]] 210 | }) 211 | } 212 | 213 | /// Mirror shape `1d -> 3d` around xz-plane at y coordinate. 214 | pub fn my( 215 | y: U, 216 | a: Arc [U; 3] + Sync + Send> 217 | ) -> Arc [U; 3] + Sync + Send> 218 | where f64: Cast 219 | { 220 | return Arc::new(move |t| { 221 | let pos = a(t); 222 | [pos[0], 2.0.cast() * y - pos[1], pos[2]] 223 | }) 224 | } 225 | 226 | /// Mirror shape `1d -> 3d` around xy-plane at z coordinate. 227 | pub fn mz( 228 | z: U, 229 | a: Arc [U; 3] + Sync + Send> 230 | ) -> Arc [U; 3] + Sync + Send> 231 | where f64: Cast 232 | { 233 | return Arc::new(move |t| { 234 | let pos = a(t); 235 | [pos[0], pos[1], 2.0.cast() * z - pos[2]] 236 | }) 237 | } 238 | 239 | /// Bake mirror `2d -> 3d` around yz-plane at x coordinate. 240 | pub fn mirx2(x: T, a: Fn2) -> Fn2 241 | where f64: Cast 242 | { 243 | conx2(0.5.cast(), a.clone(), mx(x, a)) 244 | } 245 | 246 | /// Bake mirror `2d -> 3d` around xz-plane at y coordinate. 247 | pub fn miry2(y: T, a: Fn2) -> Fn2 248 | where f64: Cast 249 | { 250 | cony2(0.5.cast(), a.clone(), my(y, a)) 251 | } 252 | 253 | /// Bake mirror `3d -> 3d` around yz-plane at x coordinate. 254 | pub fn mirx3(x: T, a: Fn3) -> Fn3 255 | where f64: Cast 256 | { 257 | conx3(0.5.cast(), a.clone(), mx(x, a)) 258 | } 259 | 260 | /// Bake mirror `3d -> 3d` around xz-plane at y coordinate. 261 | pub fn miry3(y: T, a: Fn3) -> Fn3 262 | where f64: Cast 263 | { 264 | cony3(0.5.cast(), a.clone(), my(y, a)) 265 | } 266 | 267 | /// Bake mirror `3d -> 3d` around xy-plane at z coordinate. 268 | pub fn mirz3(z: T, a: Fn3) -> Fn3 269 | where f64: Cast 270 | { 271 | conz3(0.5.cast(), a.clone(), mz(z, a)) 272 | } 273 | 274 | /// Reverses input direction. 275 | pub fn rev(a: Fn1) -> Fn1 { 276 | seg1([One::one(), Zero::zero()], a) 277 | } 278 | 279 | /// Offsets `3d -> 3d` at position. 280 | pub fn off( 281 | pos: [U; 3], 282 | a: Arc [U; 3] + Sync + Send> 283 | ) -> Arc [U; 3] + Sync + Send> { 284 | return Arc::new(move |t| add3(a(t), pos)) 285 | } 286 | 287 | /// Gets the contour line of a curved quad. 288 | /// 289 | /// ```ignore 290 | /// 0.0-0.25: [0.0, 0.0] -> [1.0, 0.0] 291 | /// 0.25-0.5: [1.0, 0.0] -> [1.0, 1.0] 292 | /// 0.5-0.75: [1.0, 1.0] -> [0.0, 1.0] 293 | /// 0.75-1.0: [0.0, 1.0] -> [0.0, 0.0] 294 | /// ``` 295 | pub fn contour(a: Fn2) -> Fn1 296 | where f64: Cast 297 | { 298 | let _025: T = 0.25.cast(); 299 | let _4: T = 4.0.cast(); 300 | let _0: T = 0.0.cast(); 301 | let _05: T = 0.5.cast(); 302 | let _1: T = 1.0.cast(); 303 | let _075 = 0.75.cast(); 304 | return Arc::new(move |t| { 305 | if t < _025 {a([_4 * t, _0])} 306 | else if t < _05 {a([_1, _4 * (t - _025)])} 307 | else if t < _075 {a([_1 - _4 * (t - _05), _1])} 308 | else {a([_0, _1 - _4 * (t - _075)])} 309 | }) 310 | } 311 | 312 | /// Adds a margin to input of a `1d -> 3d` function. 313 | pub fn margin1(m: T, a: Fn1) -> Fn1 314 | where f64: Cast 315 | { 316 | let _1 = 1.0.cast(); 317 | let _2 = 2.0.cast(); 318 | let s = _1 / (_1 + _2 * m); 319 | return Arc::new(move |t| a((t + m) * s)) 320 | } 321 | 322 | /// Adds a margin to input of a `2d -> 3d` function. 323 | pub fn margin2(m: T, a: Fn2) -> Fn2 324 | where f64: Cast 325 | { 326 | let _1 = 1.0.cast(); 327 | let _2 = 2.0.cast(); 328 | let s = _1 / (_1 + _2 * m); 329 | return Arc::new(move |t| a([(t[0] + m) * s, (t[1] + m) * s])) 330 | } 331 | 332 | /// Adds a margin to input of a `3d -> 3d` function. 333 | pub fn margin3(m: T, a: Fn3) -> Fn3 334 | where f64: Cast 335 | { 336 | let _1 = 1.0.cast(); 337 | let _2 = 2.0.cast(); 338 | let s = _1 / (_1 + _2 * m); 339 | return Arc::new(move |t| a([(t[0] + m) * s, (t[1] + m) * s, (t[2] + m) * s])) 340 | } 341 | 342 | /// Creates a circle located at a center and with a radius. 343 | /// 344 | /// The first input argument is the angle starting at 0, 345 | /// rotating 360 degrees around the center endering at 1. 346 | /// The second input argument is the radius starting at 0 ending at 1. 347 | /// 348 | /// The circle is flat along the z axis. 349 | pub fn circle(center: [T; 3], radius: T) -> Fn2 350 | where f64: Cast 351 | { 352 | let two_pi = 6.283185307179586.cast(); 353 | return Arc::new(move |t| { 354 | let angle = t[0] * two_pi; 355 | [ 356 | center[0] + radius * t[1] * angle.cos(), 357 | center[1] + radius * t[1] * angle.sin(), 358 | center[2] 359 | ] 360 | }) 361 | } 362 | 363 | /// Creates a sphere located at a center and with a radius. 364 | /// 365 | /// The two first arguments are angles, the third is radius. 366 | /// The first input argument controls rotation around the z axis. 367 | /// The second input argument starts at the top of the sphere 368 | /// and moves down to the bottom of the sphere. 369 | pub fn sphere(center: [T; 3], radius: T) -> Fn3 370 | where f64: Cast 371 | { 372 | let two_pi = 6.283185307179586.cast(); 373 | let _1 = 1.0.cast(); 374 | let _2 = 2.0.cast(); 375 | return Arc::new(move |t| { 376 | let angle0 = t[0] * two_pi; 377 | let tx = _2 * t[1] - _1; 378 | let rad = radius * (_1 - tx * tx).sqrt(); 379 | [ 380 | center[0] + rad * t[2] * angle0.cos(), 381 | center[1] + rad * t[2] * angle0.sin(), 382 | center[2] - radius + _2 * radius * t[1], 383 | ] 384 | }) 385 | } 386 | 387 | /// Intersects a curved quad at x-line. 388 | pub fn x2(x: T, a: Fn2) -> Fn1 389 | where f64: Cast 390 | { 391 | return Arc::new(move |t| a([x, t])) 392 | } 393 | 394 | /// Intersects a curved quad at y-line. 395 | pub fn y2(y: T, a: Fn2) -> Fn1 { 396 | return Arc::new(move |t| a([t, y])) 397 | } 398 | 399 | /// Intersects a curved cube at x-plane. 400 | pub fn x3(x: T, a: Fn3) -> Fn2 { 401 | return Arc::new(move |t| a([x, t[0], t[1]])) 402 | } 403 | 404 | /// Intersects a curved cube at y-plane. 405 | pub fn y3(y: T, a: Fn3) -> Fn2 { 406 | return Arc::new(move |t| a([t[0], y, t[1]])) 407 | } 408 | 409 | /// Intersects a curved cube at z-plane. 410 | pub fn z3(z: T, a: Fn3) -> Fn2 { 411 | return Arc::new(move |t| a([t[0], t[1], z])) 412 | } 413 | 414 | /// Extends a 1d shape into 2d by adding a 415 | /// vector to the result generated by a 1d shape. 416 | pub fn ext1(a: Fn1, b: Fn1) -> Fn2 { 417 | return Arc::new(move |t| add3(a(t[0]), b(t[1]))) 418 | } 419 | 420 | /// Extends a 2d shape into 3d by adding 421 | /// a vector to the result generated by a 1d shape. 422 | pub fn ext2(a: Fn1, b: Fn2) -> Fn3 { 423 | return Arc::new(move |t| add3(a(t[0]), b([t[1], t[2]]))) 424 | } 425 | 426 | /// Uses a range to pick a segment of a curve. 427 | pub fn seg1(range: [T; 2], a: Fn1) -> Fn1 { 428 | return Arc::new(move |t| a(range[0] + (range[1] - range[0]) * t)) 429 | } 430 | --------------------------------------------------------------------------------