1  # DreamTalk API Reference
  2  
  3  This document provides comprehensive documentation for creating DreamTalk scenes. DreamTalk is a programmatic animation library for Cinema 4D, inspired by 3blue1brown's manim.
  4  
  5  ## Quick Start
  6  
  7  ```python
  8  from DreamTalk.imports import *
  9  
 10  class MyScene(TwoDScene):
 11      def construct(self):
 12          circle = Circle(radius=100, color=BLUE)
 13          self.play(Create(circle), run_time=1)
 14          self.wait(0.5)
 15  
 16  scene = MyScene(resolution="default", save=False)
 17  ```
 18  
 19  ---
 20  
 21  ## Scene Classes
 22  
 23  ### TwoDScene
 24  2D scene with orthographic camera. Best for mathematical visualizations.
 25  
 26  ```python
 27  class MyScene(TwoDScene):
 28      def construct(self):
 29          # Your scene construction here
 30          pass
 31  
 32  scene = MyScene(resolution="default", alpha=True, save=False)
 33  ```
 34  
 35  ### ThreeDScene
 36  3D scene with perspective camera.
 37  
 38  ```python
 39  class My3DScene(ThreeDScene):
 40      def construct(self):
 41          sphere = Sphere(radius=100, color=RED)
 42          self.play(Create(sphere), run_time=1)
 43  ```
 44  
 45  ### Scene Parameters
 46  - `resolution`: "verylow" (320x180), "low" (480x270), "default" (1280x720), "high" (2560x1440), "veryhigh" (3840x2160)
 47  - `alpha`: Enable alpha channel (default: True)
 48  - `save`: Auto-save render (default: False)
 49  
 50  ### Scene Methods
 51  - `play(*animators, run_time=1)` - Execute animations over specified time
 52  - `set(*animators)` - Instant animation (2 frames)
 53  - `wait(seconds)` - Pause without animation
 54  - `START()` / `STOP()` - Mark timeline boundaries
 55  
 56  ---
 57  
 58  ## Line Objects (Splines)
 59  
 60  All line objects render as sketch/outline strokes.
 61  
 62  ### Circle
 63  ```python
 64  circle = Circle(
 65      radius=200,           # Radius in units
 66      ellipse_ratio=1,      # 0-1, creates ellipse when < 1
 67      ring_ratio=1,         # 0-1, creates ring when < 1
 68      color=BLUE,           # Color constant or c4d.Vector
 69      x=0, y=0, z=0,        # Position
 70      name="MyCircle"       # Optional name
 71  )
 72  
 73  # Animation method
 74  circle.change_radius(radius=300)  # Returns ScalarAnimation
 75  ```
 76  
 77  ### Rectangle
 78  ```python
 79  rect = Rectangle(
 80      width=100,
 81      height=100,
 82      rounding=0,           # 0-1, corner rounding ratio
 83      color=RED
 84  )
 85  ```
 86  
 87  ### Square
 88  ```python
 89  square = Square(size=100, color=GREEN)
 90  ```
 91  
 92  ### Arc
 93  ```python
 94  arc = Arc(
 95      radius=150,
 96      start_angle=0,        # Radians
 97      end_angle=PI/2,       # Radians
 98      color=PURPLE
 99  )
100  ```
101  
102  ### Triangle
103  ```python
104  triangle = Triangle(radius=100, color=YELLOW)
105  ```
106  
107  ### NSide (Regular Polygon)
108  ```python
109  hexagon = NSide(radius=100, point_count=6, color=BLUE)
110  ```
111  
112  ### Spline (Custom Points)
113  ```python
114  spline = Spline(
115      points=[(0, 0, 0), (100, 50, 0), (200, 0, 0)],
116      spline_type="bezier",  # "linear", "cubic", "akima", "b-spline", "bezier"
117      color=WHITE
118  )
119  ```
120  
121  ### SplineText
122  ```python
123  text = SplineText(
124      text="Hello World",
125      height=50,
126      anchor="center",      # "left", "center", "right"
127      seperate_letters=False,
128      draw_order="left_to_right",
129      color=WHITE
130  )
131  ```
132  
133  ### Helix
134  ```python
135  helix = Helix(
136      start_radius=200,
137      end_radius=200,
138      start_angle=0,
139      end_angle=2*PI,
140      height=200,
141      subdivision=100,
142      color=BLUE
143  )
144  ```
145  
146  ### SVG (Import SVG File)
147  ```python
148  # Uses global SVG_PATH
149  svg = SVG(file_name="my_icon", x=0, y=0, z=0)
150  
151  # Or with custom assets path (for sovereign symbols)
152  svg = SVG(file_name="my_icon", assets_path="/path/to/assets")
153  ```
154  
155  ### SplineMask (Boolean Operations)
156  ```python
157  mask = SplineMask(
158      circle, rect,         # Input splines
159      mode="union",         # "union", "a-b", "b-a", "and", "or", "intersection"
160      axis="xz"
161  )
162  ```
163  
164  ### SplineSymmetry
165  ```python
166  sym = SplineSymmetry(spline, axis="x")  # "x", "y", "z"
167  ```
168  
169  ---
170  
171  ## Solid Objects (3D Primitives)
172  
173  All solid objects have fill materials and optional sketch outlines.
174  
175  ### Sphere
176  ```python
177  sphere = Sphere(
178      radius=100,
179      filled=1,             # 0-1, fill amount
180      color=RED,
181      glow=False,           # Enable glow capability
182      brightness=0.8        # Glow brightness if enabled
183  )
184  ```
185  
186  ### Cube
187  ```python
188  cube = Cube(
189      width=100,
190      height=100,
191      depth=100,
192      size=None,            # If set, overrides width/height/depth
193      color=BLUE
194  )
195  ```
196  
197  ### Cylinder
198  ```python
199  cylinder = Cylinder(
200      radius=50,
201      height=150,
202      orientation="x+",     # "x+", "x-", "y+", "y-", "z+", "z-"
203      color=GREEN
204  )
205  ```
206  
207  ### Cone
208  ```python
209  cone = Cone(
210      radius=50,
211      height=150,
212      orientation="y+",
213      color=YELLOW
214  )
215  ```
216  
217  ### Plane
218  ```python
219  plane = Plane(
220      width=400,
221      height=400,
222      width_segments=10,
223      height_segments=10,
224      orientation="z+",
225      color=WHITE
226  )
227  ```
228  
229  ### Extrude
230  ```python
231  extrude = Extrude(
232      circle, rect,         # Child splines to extrude
233      offset=50,            # Extrusion depth
234      color=BLUE
235  )
236  ```
237  
238  ### Loft
239  ```python
240  loft = Loft(color=RED)
241  # Add profile splines as children
242  ```
243  
244  ### SweepNurbs
245  ```python
246  sweep = SweepNurbs(
247      rail=helix,           # Path spline
248      profile=circle,       # Profile spline
249      color=PURPLE
250  )
251  ```
252  
253  ### Boole (Boolean Operations)
254  ```python
255  boole = Boole(
256      cube, sphere,         # Objects to combine
257      mode="subtract",      # "union", "subtract", "intersect", "without"
258      color=RED
259  )
260  ```
261  
262  ### MetaBall
263  ```python
264  meta = MetaBall(
265      sphere1, sphere2,     # Children
266      hull_value=1,
267      subdivision=5,
268      color=GREEN
269  )
270  ```
271  
272  ---
273  
274  ## Custom Objects (Composites)
275  
276  ### Group
277  ```python
278  group = Group(circle, rect, sphere, name="MyGroup")
279  
280  # Iteration
281  for obj in group:
282      print(obj)
283  
284  # Indexing
285  first = group[0]
286  
287  # Add children
288  group.add(new_circle)
289  
290  # Positioning utilities
291  group.position_on_line(point_ini=(-200, 0, 0), point_fin=(200, 0, 0))
292  group.position_on_circle(radius=150, plane="xy")
293  group.position_on_spline(path_spline)
294  
295  # Create connections between all children
296  connections = group.create_connections(completeness=0.5, turbulence=False)
297  ```
298  
299  ### Connection
300  ```python
301  connection = Connection(
302      object_a, object_b,
303      turbulence=False,
304      arrow_end=True
305  )
306  ```
307  
308  ---
309  
310  ## Animators
311  
312  Animators wrap objects and call their animation methods.
313  
314  ### Creation/Destruction
315  ```python
316  self.play(Create(obj), run_time=1)      # Animate creation
317  self.play(UnCreate(obj), run_time=1)    # Animate destruction
318  ```
319  
320  ### Drawing (Line Objects)
321  ```python
322  self.play(Draw(line_obj), run_time=1)   # Draw stroke
323  self.play(UnDraw(line_obj), run_time=1) # Undraw stroke
324  ```
325  
326  ### Visibility
327  ```python
328  self.play(FadeIn(obj), run_time=0.5)
329  self.play(FadeOut(obj), run_time=0.5)
330  ```
331  
332  ### Fill (Solid Objects)
333  ```python
334  self.play(Fill(solid_obj), run_time=1)
335  self.play(UnFill(solid_obj), run_time=1)
336  ```
337  
338  ### Glow (Solid Objects with glow=True)
339  ```python
340  self.play(Glow(sphere), run_time=0.5)
341  self.play(UnGlow(sphere), run_time=0.5)
342  ```
343  
344  ### Transform
345  ```python
346  self.play(Move(obj, x=100, y=50, z=0), run_time=1)
347  self.play(Rotate(obj, h=PI/2, p=0, b=0), run_time=1)
348  self.play(Scale(obj, scale=2), run_time=1)
349  ```
350  
351  ### Color
352  ```python
353  self.play(ChangeColor(obj, color=RED), run_time=0.5)
354  ```
355  
356  ### Morph
357  ```python
358  self.play(Morph(circle, square), run_time=1)
359  ```
360  
361  ### Connect
362  ```python
363  self.play(Connect(obj_a, obj_b, arrow=True), run_time=1)
364  self.play(UnConnect(obj_a, obj_b), run_time=1)
365  ```
366  
367  ### Animator Parameters
368  All animators accept:
369  - `rel_start=0` - Relative start time (0-1)
370  - `rel_stop=1` - Relative stop time (0-1)
371  - `unpack_groups=True` - Whether to animate group children individually
372  
373  ---
374  
375  ## Animation Timing
376  
377  ### Sequential Animations
378  ```python
379  self.play(Create(circle), run_time=1)
380  self.play(Move(circle, x=100), run_time=1)
381  ```
382  
383  ### Simultaneous Animations
384  ```python
385  self.play(
386      Create(circle),
387      Move(rect, x=100),
388      run_time=1
389  )
390  ```
391  
392  ### Staggered Animations
393  ```python
394  self.play(
395      Create(circle, rel_start=0, rel_stop=0.5),
396      Create(rect, rel_start=0.5, rel_stop=1),
397      run_time=2
398  )
399  ```
400  
401  ---
402  
403  ## Constants
404  
405  ### Colors
406  ```python
407  BLUE = c4d.Vector(0, 162, 255) / 255
408  RED = c4d.Vector(255, 100, 78) / 255
409  PURPLE = average_color(RED, BLUE)
410  YELLOW = c4d.Vector(218, 218, 88) / 255
411  GREEN = c4d.Vector(71, 196, 143) / 255
412  WHITE = c4d.Vector(255, 255, 255) / 255
413  BLACK = c4d.Vector(0, 0, 0) / 255
414  ```
415  
416  ### Math
417  ```python
418  PI = 3.141592653589793
419  ```
420  
421  ### Project Settings
422  ```python
423  FPS = 30
424  ASPECT_RATIO = 16/9
425  ```
426  
427  ---
428  
429  ## Common Object Parameters
430  
431  All objects accept these base parameters:
432  - `x`, `y`, `z` - Initial position
433  - `color` - Color (use constants or c4d.Vector)
434  - `name` - Object name
435  - `visible` - Initial visibility (default: True)
436  - `plane` - Orientation plane: "xy", "yz", "xz"
437  
438  ### LineObject Additional Parameters
439  - `draw_order` - "left_to_right", "right_to_left", "short_to_long", "long_to_short"
440  - `arrow_start`, `arrow_end` - Add arrows
441  - `stroke_width` - Line thickness (default: 5)
442  
443  ### SolidObject Additional Parameters
444  - `filled` - Fill amount 0-1
445  - `glow` - Enable glow (default: False)
446  - `brightness` - Glow brightness
447  
448  ---
449  
450  ## Object Methods
451  
452  ### All Objects
453  ```python
454  obj.set_position(x=0, y=0, z=0)
455  obj.set_position(position=c4d.Vector(x, y, z))
456  obj.set_rotation(h=0, p=0, b=0)
457  obj.set_scale(scale=1)  # Uniform
458  obj.set_scale(x=1, y=1, z=1)  # Non-uniform
459  
460  obj.move(x=100)  # Returns VectorAnimation
461  obj.rotate(h=PI/2)  # Returns VectorAnimation
462  obj.scale(scale=2)  # Returns ScalarAnimation
463  
464  obj.get_center()  # Returns c4d.Vector
465  obj.get_bounding_box()  # Returns (width, height, depth)
466  ```
467  
468  ### LineObject Methods
469  ```python
470  line.draw(completion=1)  # Returns ScalarAnimation
471  line.un_draw(completion=0)
472  line.fade_in(completion=1)
473  line.fade_out(completion=0)
474  line.change_color(color=RED)  # Returns ColorAnimation
475  ```
476  
477  ### SolidObject Methods
478  ```python
479  solid.fill(completion=1)
480  solid.un_fill(completion=0)
481  solid.glow(completion=1)  # If glow=True
482  solid.un_glow(completion=0)
483  solid.draw(completion=1)  # Sketch outline
484  solid.un_draw(completion=0)
485  ```
486  
487  ### CustomObject Methods
488  ```python
489  custom.create(completion=1)
490  custom.un_create(completion=0)
491  ```
492  
493  ---
494  
495  ## Complete Example
496  
497  ```python
498  from DreamTalk.imports import *
499  
500  class TaylorSeriesDemo(TwoDScene):
501      def construct(self):
502          # Create objects
503          title = SplineText("Taylor Series", height=40, color=WHITE, y=300)
504          circle = Circle(radius=100, color=BLUE)
505          squares = Group(*[
506              Square(size=30, color=RED, x=-150 + i*50)
507              for i in range(7)
508          ])
509  
510          # Animate title
511          self.play(Draw(title), run_time=1)
512          self.wait(0.5)
513  
514          # Create circle
515          self.play(Create(circle), run_time=1)
516  
517          # Create squares with stagger
518          self.play(Create(squares), run_time=2)
519  
520          # Move and transform
521          self.play(
522              Move(circle, y=-100),
523              Scale(squares, scale=0.5),
524              run_time=1
525          )
526  
527          # Connect objects
528          self.play(Connect(circle, squares), run_time=1)
529  
530          # Final wait
531          self.wait(1)
532  
533  scene = TaylorSeriesDemo(resolution="default", save=False)
534  ```
535  
536  ---
537  
538  ## Sketch-Based Objects (Sovereign Symbols)
539  
540  These objects load SVG files and are designed as reusable symbols:
541  
542  ```python
543  # Built-in symbols (in sketch_objects.py)
544  fire = Fire(glow=True, brightness=0.8)  # Fire symbol with optional glow
545  human = Human(color=BLUE)               # Human figure
546  
547  # The Sketch base class for custom SVG symbols
548  class MySymbol(Sketch):
549      def __init__(self, **kwargs):
550          super().__init__(file_name="my_symbol", **kwargs)
551  ```
552  
553  ---
554  
555  ## Tips for Scene Creation
556  
557  1. **Start simple**: Create objects first, then add animations
558  2. **Use groups**: Group related objects for easier manipulation
559  3. **Timing**: Use `rel_start`/`rel_stop` for complex timing
560  4. **Colors**: Stick to the built-in color constants for consistency
561  5. **Resolution**: Use "low" for iteration, "default" or higher for final renders
562  6. **Wait calls**: Add `self.wait()` between sequences for breathing room