Debian Codegraph @

texmf-dist/doc/latex/tikz-sections/README.md

raw
1 # TikZ-Sections
2
3 A TikZ-LaTeX package for drawing structural cross-sections.
4
5 ## Package information
6
7 - Version: 0.2.0
8 - Author: Parsa Yazdi
9 - Maintainer: Parsa Yazdi
10 - License: LaTeX Project Public License 1.3c or later
11 - Repository: <https://github.com/someparsa/TikZ-Sections>
12 - Bug tracker: <https://github.com/someparsa/TikZ-Sections/issues>
13
14 ## Aim
15
16 Preparing high-quality structural engineering figures for papers and reports is
17 time-consuming. TikZ-Sections aims to make this easier for engineers and academics
18 working with steel and reinforced-concrete sections.
19
20 ## Tools
21
22 This package is built on top of TikZ, so normal TikZ features can be used around
23 and alongside TikZ-Sections drawings. A LaTeX distribution with TikZ/PGF is
24 required.
25
26 ## Installation
27
28 Clone this repository or download a release archive.
29
30 ```sh
31 git clone https://github.com/someparsa/TikZ-Sections.git
32 ```
33
34 Put the `.sty` file in the directory where you save your LaTeX file. Then import the package like any other standard packages in LaTeX system.
35
36 ```tex
37 \usepackage{tikz-sections}
38 ```
39
40 ## Quick example
41
42 ```tex
43 \documentclass[margin=2mm]{standalone}
44 \usepackage{tikz-sections}
45
46 \begin{document}
47 \begin{tikzpicture}
48 \TikZSectionsChannel[
49 depth=245,
50 flange=75,
51 lip=20,
52 thickness=2.5,
53 radius=5
54 ]
55 \end{tikzpicture}
56 \end{document}
57 ```
58
59 The command above draws a lipped cold-formed channel using:
60
61 ```text
62 \TikZSectionsChannel[depth=..., flange=..., lip=..., thickness=..., radius=...]
63 ```
64
65 Use `flange` and `lip` for equal top/bottom values, or override them with
66 `top flange`, `bottom flange`, `top lip`, and `bottom lip` when the section is
67 asymmetric. Asymmetric channel and zee dimensions are part of the detailed input
68 mode, so use `detailed=true` with those independent keys.
69
70 Set `lip=0` or set both `top lip=0` and `bottom lip=0` to draw the unlipped
71 form through the same channel/zee geometry path.
72
73 ## Current status
74
75 The package is being refactored gradually toward a documented CTAN-ready
76 release. Version 0.2.0 is the staged baseline for the first CTAN submission
77 candidate and includes:
78
79 - Package metadata and package-safe TikZ dependency loading.
80 - Configurable TikZ styles for straight segments, curved segments, labels,
81 dimensions, hidden lines, and fills.
82 - Legacy drawing commands such as `\csChannel`, `\csBox`, `\csZee`, `\csL`,
83 `\csTube`, `\csUBC`, and related HRS commands.
84 - New explicit cold-formed steel commands with `\csCFS...` names.
85 - New explicit hot-rolled steel commands with `\csHRS...` names.
86 - Initial reinforced-concrete cross-section commands with `\TikZRC...` names.
87 - Key-value public commands with `\TikZSections...` names.
88 - Built-up section sketches are intentionally left to normal TikZ composition
89 instead of package-specific commands.
90
91 ## Recent improvements
92
93 Recent development work has focused on making the package CTAN-facing as
94 `tikz-sections` and making the TikZ integration more predictable:
95
96 - Renamed the public package surface to `tikz-sections`.
97 - Removed unreleased predecessor package markers and compatibility shims.
98 - Removed package-owned built-up section commands; built-up assemblies are now
99 composed with ordinary TikZ scopes and transforms.
100 - Added TikZ-like placement keys `at={(x,y)}` and `shift={(x,y)}`.
101 - Added local `xscale` and `yscale` keys alongside `scale` and `rotate`.
102 - Standardized CFS channel and zee inputs so `flange` and `lip` are common
103 defaults, with `top flange`, `bottom flange`, `top lip`, and `bottom lip`
104 available as independent overrides.
105 - Defined simplified CFS input as the nominal symmetric mode and detailed CFS
106 input as the mode that honors independent top/bottom flange and lip values.
107 - Consolidated lipped and unlipped public channel/zee variants into
108 `\TikZSectionsChannel` and `\TikZSectionsZee`.
109 - Changed channel and zee `dimensions=true` from generic dimension guide lines
110 to a compact dimension legend for web depth, flange, lip, thickness, and
111 radius.
112 - Documented and tested `lip=0` as the unlipped channel/zee form.
113 - Added general lower-level CFS handlers for asymmetric channel and zee
114 geometry.
115 - Normalized public circular section wrappers so their local drawing extent
116 starts from a south-west origin.
117 - Added a smoke test covering ordinary TikZ composition with scopes, shifts,
118 rotation, mirroring, nodes, fills, and drawing commands.
119 - Updated the manual and examples to use the `tikz-sections` package name and
120 `\TikZSections...` public command prefix.
121
122 ## Key-value API
123
124 The recommended public API is the newer key-value interface. These commands use
125 readable option names and provide defaults for omitted values:
126
127 ```tex
128 \TikZSectionsChannel[
129 depth=245,
130 flange=75,
131 thickness=2.5,
132 radius=5,
133 centerline=true,
134 dimensions=true,
135 label=C245,
136 at={(0,0)},
137 scale=0.2,
138 xscale=1,
139 yscale=1,
140 rotate=0,
141 x=0,
142 y=0
143 ]
144 ```
145
146 Common keys include:
147
148 - `depth`
149 - `width`
150 - `diameter`
151 - `flange`
152 - `top flange`
153 - `bottom flange`
154 - `left flange`
155 - `right flange`
156 - `lip`
157 - `top lip`
158 - `bottom lip`
159 - `thickness`
160 - `radius`
161 - `inside radius`
162 - `bend radius`
163 - `root radius`
164 - `position`
165 - `stiffener position`
166 - `leg`
167 - `vertical leg`
168 - `horizontal leg`
169 - `web depth`
170 - `web thickness`
171 - `flange thickness`
172 - `top flange width`
173 - `top flange thickness`
174 - `bottom flange width`
175 - `bottom flange thickness`
176 - `reference line width`
177 - `line width`
178 - `cover`
179 - `bar diameter`
180 - `top bars`
181 - `bottom bars`
182 - `left bars`
183 - `right bars`
184 - `top layers`
185 - `bottom layers`
186 - `side layers`
187 - `layer spacing`
188 - `perimeter bars`
189 - `label`
190 - `label x`
191 - `label y`
192 - `mode`
193 - `simplified`
194 - `detailed`
195 - `filled`
196 - `centerline`
197 - `dimensions`
198 - `monochrome`
199 - `tie`
200 - `at`
201 - `shift`
202 - `scale`
203 - `xscale`
204 - `yscale`
205 - `rotate`
206 - `x`
207 - `y`
208
209 ### Current dimension overlay
210
211 The `dimensions=true` key currently enables basic visual dimension assistance.
212 For `\TikZSectionsChannel` and `\TikZSectionsZee`, it draws a compact boxed
213 legend near the section using labels such as `b_w=180 mm`, `b_f=55 mm`,
214 `b_l=18 mm`, `t=2 mm`, and `r=4 mm`. Other section families still use the older
215 generic horizontal and vertical dimension guide overlay until they receive
216 section-specific dimension displays.
217
218 This is not yet a full engineering dimensioning system. It does not currently
219 draw traditional engineering dimension lines, extension lines, standard offsets,
220 unit formatting controls, or standard-specific notation. The current direction is
221 to use robust parameter legends first, then keep traditional dimension lines as a
222 later subsystem.
223
224 When `label=...` is supplied without `label x` and `label y`, the label is
225 placed above the top-left of the section and includes the local drawing scale in
226 brackets, for example `C245 (scale 0.03)`.
227
228 ### Simplified and detailed input modes
229
230 The default public mode is `simplified`. For CFS channel and zee commands,
231 simplified mode uses the nominal symmetric inputs:
232
233 ```tex
234 \TikZSectionsChannel[depth=180, flange=55, lip=18]
235 ```
236
237 In simplified mode, `flange` is applied to both top and bottom flanges, and
238 `lip` is applied to both lips. Independent top/bottom values are intentionally
239 ignored in this mode.
240
241 Use `detailed=true` or `mode=detailed` when the section geometry is asymmetric:
242
243 ```tex
244 \TikZSectionsChannel[
245 detailed=true,
246 depth=180,
247 top flange=55,
248 bottom flange=60,
249 top lip=18,
250 bottom lip=20
251 ]
252 ```
253
254 Current key-value commands:
255
256 - `\TikZSectionsChannel`
257 - `\TikZSectionsStiffenedChannel`
258 - `\TikZSectionsZee`
259 - `\TikZSectionsSigma`
260 - `\TikZSectionsHat`
261 - `\TikZSectionsAngle`
262 - `\TikZSectionsLippedAngle`
263 - `\TikZSectionsRHS`
264 - `\TikZSectionsSHS`
265 - `\TikZSectionsCHS`
266 - `\TikZSectionsUniversalBeam`
267 - `\TikZSectionsUniversalColumn`
268 - `\TikZSectionsWeldedI`
269 - `\TikZSectionsTee`
270 - `\TikZSectionsHRSChannel`
271 - `\TikZSectionsEqualAngle`
272 - `\TikZSectionsUnequalAngle`
273 - `\TikZSectionsPlate`
274 - `\TikZSectionsFlatBar`
275 - `\TikZSectionsRoundBar`
276 - `\TikZSectionsHRSCHS`
277 - `\TikZSectionsHRSRHS`
278 - `\TikZSectionsHRSSHS`
279 - `\TikZRCRectangular`
280 - `\TikZRCCircular`
281
282 Positional helper commands remain available for lower-level drawing control.
283
284 ## TikZ integration
285
286 Public section commands draw into the current `tikzpicture`; they do not create
287 a `tikzpicture` internally. They can be placed inside normal TikZ scopes and
288 combined with ordinary TikZ commands such as `\draw`, `\fill`, `\node`, and
289 `\foreach`.
290
291 Use `at={(x,y)}` or `shift={(x,y)}` for placement. The older `x=...` and
292 `y=...` keys remain as equivalent scalar placement keys. The `scale`,
293 `xscale`, `yscale`, and `rotate` keys apply a local transform to the section and
294 also respect any surrounding TikZ transform.
295
296 ## Cold-formed steel commands
297
298 The current CFS API covers single-section primitives. Channel and zee families
299 can be drawn with equal flange/lip values or with independent top and bottom
300 values from the same public command. Equal values are the simplified default;
301 independent top and bottom values require `detailed=true`. Use `lip=0`, or both
302 `top lip=0` and `bottom lip=0`, for unlipped variants through the same geometry
303 path. Built-up CFS assemblies are composed with ordinary TikZ scopes rather than
304 package-specific built-up commands.
305
306 Public CFS key-value commands currently available:
307
308 - `\TikZSectionsChannel`
309 - `\TikZSectionsStiffenedChannel`
310 - `\TikZSectionsZee`
311 - `\TikZSectionsSigma`
312 - `\TikZSectionsHat`
313 - `\TikZSectionsAngle`
314 - `\TikZSectionsLippedAngle`
315 - `\TikZSectionsRHS`
316 - `\TikZSectionsSHS`
317 - `\TikZSectionsCHS`
318
319 Useful CFS input patterns:
320
321 ```tex
322 % Equal flanges and lips
323 \TikZSectionsChannel[depth=180, flange=55, lip=18]
324
325 % Independent top/bottom flanges and lips
326 \TikZSectionsChannel[
327 detailed=true,
328 depth=180,
329 top flange=55,
330 top lip=18,
331 bottom flange=60,
332 bottom lip=20
333 ]
334
335 % Unlipped form through the same channel command
336 \TikZSectionsChannel[depth=180, flange=55, lip=0]
337 ```
338
339 Single open sections:
340
341 - `\csCFSChannel{depth}{flange}{thickness}{radius}`
342 - `\csCFSLippedChannel{depth}{flange}{lip}{thickness}{radius}`
343 - `\csCFSChannelGeneral{depth}{top flange}{top lip}{bottom flange}{bottom lip}{thickness}{radius}`
344 - `\csCFSEdgeStiffenedChannel{depth}{flange}{lip}{thickness}{radius}`
345 - `\csCFSZee{depth}{flange}{thickness}{radius}`
346 - `\csCFSLippedZee{depth}{flange}{lip}{thickness}{radius}`
347 - `\csCFSZeeGeneral{depth}{top flange}{top lip}{bottom flange}{bottom lip}{thickness}{radius}`
348 - `\csCFSSigma{depth}{top flange}{top lip}{bottom flange}{bottom lip}{thickness}{radius}`
349 - `\csCFSHat{depth}{left flange}{web width}{right flange}{thickness}{radius}`
350 - `\csCFSAngle{leg 1}{leg 2}{thickness}{radius}`
351 - `\csCFSLippedAngle{leg 1}{leg 2}{thickness}{radius}{lip}`
352
353 Stiffened channels:
354
355 - `\csCFSChannelWithOneStiffener{depth}{top flange}{top lip}{bottom flange}{bottom lip}{thickness}{radius}{stiffener position}`
356 - `\csCFSChannelWithTwoStiffeners{depth}{top flange}{top lip}{bottom flange}{bottom lip}{thickness}{radius}`
357 - `\csCFSChannelWithThreeStiffeners{depth}{top flange}{top lip}{bottom flange}{bottom lip}{thickness}{radius}{middle stiffener position}`
358
359 Hollow and closed sections:
360
361 - `\csCFSBox{depth}{width}{thickness}{radius}`
362 - `\csCFSRHS{depth}{width}{thickness}{radius}`
363 - `\csCFSSHS{width}{thickness}{radius}`
364 - `\csCFSCHS{radius}{thickness}`
365
366 Generic folded sections:
367
368 - `\csCFSFoldedPlate{(x1,y1),(x2,y2),...}{thickness}`
369
370 ## Hot-rolled steel commands
371
372 I, tee, and channel sections:
373
374 - `\csHRSUniversalBeam{depth}{width}{flange thickness}{web thickness}{root radius}`
375 - `\csHRSUniversalColumn{depth}{width}{flange thickness}{web thickness}{root radius}`
376 - `\csHRSISection{depth}{width}{flange thickness}{web thickness}{root radius}`
377 - `\csHRSWeldedI{web depth}{web thickness}{bottom flange width}{bottom flange thickness}{top flange width}{top flange thickness}`
378 - `\csHRSTee{depth}{width}{flange thickness}{web thickness}{root radius}`
379 - `\csHRSChannel{depth}{width}{flange thickness}{web thickness}{root radius}`
380
381 Angles:
382
383 - `\csHRSEqualAngle{leg}{thickness}{root radius}`
384 - `\csHRSUnequalAngle{vertical leg}{horizontal leg}{thickness}{root radius}`
385
386 Bars, plates, and hollow sections:
387
388 - `\csHRSPlate{width}{thickness}{reference line width}`
389 - `\csHRSFlatBar{width}{thickness}{reference line width}`
390 - `\csHRSRoundBar{radius}{line width}`
391 - `\csHRSCHS{radius}{thickness}`
392 - `\csHRSRHS{depth}{width}{thickness}{radius}`
393 - `\csHRSSHS{width}{thickness}{radius}`
394
395 ## Composing sections with TikZ
396
397 The package focuses on reliable single-section primitives. Built-up assemblies
398 should be composed with ordinary TikZ scopes and transforms:
399
400 ```tex
401 \begin{tikzpicture}
402 \TikZSectionsChannel[
403 depth=180,
404 flange=55,
405 lip=18,
406 thickness=2,
407 radius=4,
408 scale=0.025
409 ]
410 \begin{scope}[shift={(4,0)}, xscale=-1]
411 \TikZSectionsChannel[
412 depth=180,
413 flange=55,
414 lip=18,
415 thickness=2,
416 radius=4,
417 scale=0.025
418 ]
419 \end{scope}
420 \end{tikzpicture}
421 ```
422
423 ## Reinforced concrete commands
424
425 The initial reinforced-concrete API focuses on simple cross-section sketches.
426 Longitudinal bars are drawn as blue filled circles, stirrups/ties are drawn in
427 red, and the concrete outline uses a heavier line weight. `cover` is interpreted
428 as the distance from the concrete face to the longitudinal bar centerline; the
429 stirrup/tie is placed around the outside edge of the longitudinal bar envelope
430 so it confines the bars.
431
432 ```tex
433 \TikZRCRectangular[
434 width=300,
435 depth=500,
436 cover=40,
437 bar diameter=18,
438 top bars=2,
439 bottom bars=3,
440 bottom layers=2,
441 layer spacing=28
442 ]
443 ```
444
445 ```tex
446 \TikZRCCircular[
447 diameter=450,
448 cover=45,
449 bar diameter=20,
450 perimeter bars=10
451 ]
452 ```
453
454 Rectangular RC keys include:
455
456 - `width`
457 - `depth`
458 - `cover`
459 - `bar diameter`
460 - `top bars`
461 - `bottom bars`
462 - `left bars`
463 - `right bars`
464 - `top layers`
465 - `bottom layers`
466 - `side layers`
467 - `layer spacing`
468 - `tie`
469
470 Circular RC keys include:
471
472 - `diameter`
473 - `cover`
474 - `bar diameter`
475 - `perimeter bars`
476 - `tie`
477
478 ## Style customization
479
480 The default drawing uses red straight segments and blue curved segments, but
481 these can now be overridden with TikZ styles:
482
483 ```tex
484 \TikZSectionsSetup{
485 tikzSections/straight/.style={tikzSections/default, black},
486 tikzSections/round/.style={tikzSections/default, gray}
487 }
488 ```
489
490 Available style hooks include:
491
492 - `tikzSections/straight`
493 - `tikzSections/round`
494 - `tikzSections/centerline`
495 - `tikzSections/hidden`
496 - `tikzSections/dimension`
497 - `tikzSections/label`
498 - `tikzSections/fill`
499 - `tikzSections/concrete`
500 - `tikzSections/concrete edge`
501 - `tikzSections/rebar`
502 - `tikzSections/tie`
503
504 The default RC styles are deliberately distinct from the steel styles: concrete
505 uses a light fill plus a heavier black edge, longitudinal bars are blue, and
506 stirrups/ties are red. They can be overridden with the same
507 `\TikZSectionsSetup` mechanism.
508
509 ## Testing
510
511 Version 0.2.0 has been checked with MacTeX using:
512
513 ```sh
514 /Library/TeX/texbin/pdflatex -interaction=nonstopmode -halt-on-error tikz-sections.tex
515 ```
516
517 The repository now includes permanent source files for documentation, examples,
518 and smoke tests:
519
520 ```text
521 docs/tikz-sections-doc.tex
522 examples/cfs-gallery.tex
523 examples/hrs-gallery.tex
524 examples/rc-gallery.tex
525 examples/style-customization.tex
526 tests/smoke-cfs.tex
527 tests/smoke-hrs.tex
528 tests/smoke-keyval.tex
529 tests/smoke-rc.tex
530 tests/smoke-tikz-integration.tex
531 ```
532
533 To compile any of these files while keeping generated outputs outside the repo:
534
535 ```sh
536 mkdir -p /private/tmp/tikz-sections-build
537 TEXINPUTS="$(pwd)//:" /Library/TeX/texbin/pdflatex \
538 -interaction=nonstopmode \
539 -halt-on-error \
540 -output-directory=/private/tmp/tikz-sections-build \
541 docs/tikz-sections-doc.tex
542 ```
543
544 During development, the documentation, examples, and smoke tests were compiled
545 successfully with MacTeX.
546
547 ## License
548
549 TikZ-Sections is distributed under the LaTeX Project Public License, version 1.3c
550 or later. See [LICENSE](LICENSE) for the full license text.
551
552 ## Version history and milestones
553
554 Active work is tracked in [ROADMAP.md](ROADMAP.md). Detailed release-level
555 changes are tracked in [CHANGELOG.md](CHANGELOG.md).
556
557 ### v0.2.0
558
559 - Staged the current public API and documentation as the baseline for the first
560 CTAN submission candidate.
561 - Standardized the public package surface around `tikz-sections`,
562 `\TikZSections...`, and `tikzSections/...` names.
563 - Improved CFS channel/zee simplified and detailed input behavior, dimension
564 legends, labels, and built-up composition examples.
565 - Updated RC cross-section styling and stirrup/tie placement.
566 - Continued internal helper refactoring for repeated drawing geometry.
567
568 ### v0.1.2
569
570 - Added CTAN-facing package metadata to the README.
571 - Removed tracked macOS metadata and ignored future `.DS_Store` files.
572 - Set the manual author to the current maintainer.
573 - Rebuilt and verified a clean CTAN upload archive.
574
575 ### v0.1.1
576
577 - Changed the package license to the LaTeX Project Public License, version
578 1.3c or later.
579 - Added the LPPL package notice to `tikz-sections.sty`.
580
581 ### v0.1.0
582
583 - Added package metadata and package-safe TikZ dependency loading.
584 - Added configurable TikZ styles for steel segments, dimensions, labels, fills,
585 concrete, rebar, and ties.
586 - Added CFS, HRS, and RC command groups.
587 - Added the public key-value API with `\TikZSections...` and `\TikZRC...`
588 commands.
589 - Added manual source, examples, smoke tests, and build targets.
590
591 Current remaining work is tracked in [ROADMAP.md](ROADMAP.md).