Precision: Definition, Precision Handling, and Prehension Activities of the Hand

from docx import Document
from docx.shared import Pt, Inches, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.oxml.ns import qn
from docx.oxml import OxmlElement

doc = Document()

# --- Page margins ---
from docx.shared import Inches
section = doc.sections[0]
section.top_margin = Inches(1)
section.bottom_margin = Inches(1)
section.left_margin = Inches(1.2)
section.right_margin = Inches(1.2)

# --- Default font ---
normal_style = doc.styles["Normal"]
normal_style.font.name = "Calibri"
normal_style.font.size = Pt(11)

# Helper: add a coloured heading
def add_heading(doc, text, level, color=None):
    h = doc.add_heading(text, level=level)
    h.alignment = WD_ALIGN_PARAGRAPH.LEFT
    if color:
        for run in h.runs:
            run.font.color.rgb = RGBColor(*color)
    return h

# Helper: add body paragraph
def add_para(doc, text, bold_prefix=None):
    p = doc.add_paragraph()
    if bold_prefix:
        run = p.add_run(bold_prefix)
        run.bold = True
    p.add_run(text)
    p.paragraph_format.space_after = Pt(4)
    return p

# Helper: add a bullet
def add_bullet(doc, text, bold_prefix=None):
    p = doc.add_paragraph(style="List Bullet")
    if bold_prefix:
        r = p.add_run(bold_prefix)
        r.bold = True
    p.add_run(text)
    p.paragraph_format.space_after = Pt(3)
    return p

# ===================== TITLE PAGE =====================
title = doc.add_heading("Precision and Prehension Activities of the Hand", level=0)
title.alignment = WD_ALIGN_PARAGRAPH.CENTER
for run in title.runs:
    run.font.color.rgb = RGBColor(0x1F, 0x49, 0x7D)
    run.font.size = Pt(20)

sub = doc.add_paragraph("A Structured Clinical Summary")
sub.alignment = WD_ALIGN_PARAGRAPH.CENTER
sub.runs[0].font.size = Pt(13)
sub.runs[0].font.color.rgb = RGBColor(0x70, 0x70, 0x70)
doc.add_paragraph()

doc.add_page_break()

# ===================== SECTION 1: DEFINITION =====================
add_heading(doc, "1. Definition of Precision", level=1, color=(0x1F, 0x49, 0x7D))

doc.add_paragraph(
    "Precision, in the context of hand function and motor control, refers to the ability to perform "
    "fine, controlled, and accurate movements using the fingers and thumb — particularly the thumb "
    "opposing the fingers — to handle objects with exactness and delicacy. It is the hallmark of "
    "human manual dexterity and distinguishes humans from most other animals."
)
doc.add_paragraph(
    "In a broader functional sense, precision describes the quality of a movement or action that is "
    "accurate, repeatable, and finely regulated by the nervous system, allowing manipulation of objects "
    "with minimal error."
)

# ===================== SECTION 2: PREHENSION OVERVIEW =====================
add_heading(doc, "2. Prehension: Overview", level=1, color=(0x1F, 0x49, 0x7D))

doc.add_paragraph(
    "Prehension is defined as the act of grasping or taking hold of an object between any two surfaces "
    "of the hand. The thumb participates in most (but not all) prehension activities."
)

doc.add_paragraph("Prehension activities are divided into two major categories:").paragraph_format.space_after = Pt(4)

# Comparison table
table = doc.add_table(rows=8, cols=3)
table.style = "Table Grid"

# Header row
hdr = table.rows[0].cells
hdr[0].text = "Feature"
hdr[1].text = "Power Grip (Full Hand)"
hdr[2].text = "Precision Handling (Finger-Thumb)"
for cell in hdr:
    for para in cell.paragraphs:
        for run in para.runs:
            run.bold = True
    tc = cell._tc
    tcPr = tc.get_or_add_tcPr()
    shd = OxmlElement("w:shd")
    shd.set(qn("w:fill"), "1F497D")
    shd.set(qn("w:color"), "FFFFFF")
    shd.set(qn("w:val"), "clear")
    tcPr.append(shd)
    for para in cell.paragraphs:
        for run in para.runs:
            run.font.color.rgb = RGBColor(0xFF, 0xFF, 0xFF)

rows_data = [
    ("Nature", "Forceful, stabilizing", "Skillful, fine"),
    ("Palm involvement", "Yes", "No"),
    ("Thumb role", "Stabilizer", "Active participant"),
    ("Force generated", "High", "Low to moderate"),
    ("Examples", "Holding a hammer, gripping pliers", "Writing, threading a needle"),
    ("Primary muscles", "FDP, FDS (extrinsic flexors)", "Intrinsics + FDP"),
    ("Object movement", "Object moved via proximal joints", "Object manipulated by fingers"),
]
for i, (f, p, pr) in enumerate(rows_data):
    row = table.rows[i + 1].cells
    row[0].text = f
    row[1].text = p
    row[2].text = pr
    for j, cell in enumerate(row):
        tc = cell._tc
        tcPr = tc.get_or_add_tcPr()
        shd = OxmlElement("w:shd")
        fill = "DCE6F1" if i % 2 == 0 else "FFFFFF"
        shd.set(qn("w:fill"), fill)
        shd.set(qn("w:val"), "clear")
        tcPr.append(shd)

doc.add_paragraph()

# ===================== SECTION 3: PRECISION HANDLING =====================
add_heading(doc, "3. Precision Handling - In Detail", level=1, color=(0x1F, 0x49, 0x7D))

doc.add_paragraph(
    "Precision handling involves the skillful placement of an object between the fingers, or between "
    "a finger and the thumb, without involving the palm. It requires fine neuromuscular control and is "
    "mediated primarily by the intrinsic muscles of the hand (lumbricals and interossei) alongside the "
    "extrinsic flexors."
)

add_heading(doc, "3.1 Phases of Precision Handling", level=2)
phases = [
    "Opening of the hand — fingers extend; thumb abducts in preparation.",
    "Positioning the fingers — fingers adopt the appropriate configuration for the object.",
    "Bringing the fingers to the object — controlled approach.",
    "(No sustained static phase; the object is manipulated dynamically by finger movements.)",
]
for ph in phases:
    add_bullet(doc, ph)

add_heading(doc, "3.2 Subtypes of Precision Handling", level=2)

# Pad-to-pad
p = doc.add_paragraph()
r = p.add_run("a) Pad-to-Pad (Pulp Pinch)")
r.bold = True
r.font.size = Pt(11)
doc.add_paragraph(
    "Contact between the palmar pad (pulp) of the thumb and the palmar pad of a finger (usually index finger). "
    "The most common and functionally important form. Requires thumb flexion + opposition + index finger flexion."
)
p2 = doc.add_paragraph()
p2.add_run("Example: ").bold = True
p2.add_run("Picking up a coin, turning a page, picking up small objects.")

doc.add_paragraph()

# Tip-to-tip
p = doc.add_paragraph()
r = p.add_run("b) Tip-to-Tip (Tip Pinch)")
r.bold = True
r.font.size = Pt(11)
doc.add_paragraph(
    "Contact between the fingertip of the thumb and the fingertip of a finger, with slight flexion at all joints. "
    "Highest precision, lowest force among precision grips."
)
p2 = doc.add_paragraph()
p2.add_run("Example: ").bold = True
p2.add_run("Threading a needle, picking up a pin, handling a contact lens.")

doc.add_paragraph()

# Pad-to-side
p = doc.add_paragraph()
r = p.add_run("c) Pad-to-Side (Lateral Pinch / Key Grip)")
r.bold = True
r.font.size = Pt(11)
doc.add_paragraph(
    "The thumb pad presses an object against the radial (lateral) side of the index finger's middle phalanx, "
    "with MCP and IP joints of the index finger extended. Also called 'key grip' or lateral prehension."
)
p2 = doc.add_paragraph()
p2.add_run("Example: ").bold = True
p2.add_run("Holding a car key, turning a key in a lock, holding a credit card.")

doc.add_paragraph()

# Note box (simulated with shaded paragraph)
note_para = doc.add_paragraph(
    "Clinical Note: The pinch/precision grip between the thumb and index finger has fundamental importance "
    "for hand function. Loss of the thumb or index finger is considered to have a more serious impact on "
    "occupational capacity than loss of the other long fingers. (Source: THIEME Atlas of Anatomy)"
)
note_para.paragraph_format.left_indent = Inches(0.3)
note_para.paragraph_format.right_indent = Inches(0.3)
for run in note_para.runs:
    run.font.italic = True
    run.font.color.rgb = RGBColor(0x1F, 0x49, 0x7D)

doc.add_paragraph()

# ===================== SECTION 4: FOUR PRIMARY GRIP TYPES =====================
add_heading(doc, "4. Four Primary Types of Grip (THIEME Classification)", level=1, color=(0x1F, 0x49, 0x7D))

doc.add_paragraph(
    "According to the THIEME Atlas of Anatomy, all normal hand actions reduce to four primary grip types:"
)

grips = [
    ("a) Pinch / Precision Grip",
     "Object held between thumb and finger tips/pads. No palm involvement. High dexterity required."),
    ("b) Power Grip",
     "Object wrapped in the fist with all fingers flexed. Thumb acts as stabilizer. High force generated."),
    ("c) Key Grip (Lateral Pinch)",
     "Thumb pad presses object against lateral side of index finger. Used for turning keys."),
    ("d) Hook Grip",
     "Fingers flexed at all joints acting as a hook. Thumb extended or uninvolved. Used for carrying."),
]
for title_txt, desc in grips:
    p = doc.add_paragraph()
    p.add_run(title_txt + ": ").bold = True
    p.add_run(desc)
    p.paragraph_format.space_after = Pt(4)

doc.add_paragraph()

# ===================== SECTION 5: POWER GRIP SUBTYPES =====================
add_heading(doc, "5. Power Grip Subtypes", level=1, color=(0x1F, 0x49, 0x7D))

power_grips = [
    ("Cylindrical Grip",
     "All fingers wrap around a cylindrical object; wrist in neutral or slight ulnar deviation.",
     "Holding a glass, turning a door knob, gripping a hammer."),
    ("Spherical Grip",
     "Greater spread of fingers to encompass a rounded object; more interossei activity than cylindrical.",
     "Holding a ball, grasping an apple."),
    ("Hook Grip",
     "Primarily finger function (FDP, FDS); thumb in moderate to full extension. Load distally = FDP; proximally = FDS.",
     "Carrying a briefcase, hanging from a bar."),
    ("Lateral Prehension",
     "Contact between adjacent fingers; MCP and IP joints extended; extensor musculature predominates.",
     "Holding a piece of paper between two fingers."),
]
for name, desc, ex in power_grips:
    p = doc.add_paragraph()
    p.add_run(name + ": ").bold = True
    p.add_run(desc)
    p.paragraph_format.space_after = Pt(2)
    p2 = doc.add_paragraph()
    p2.add_run("Example: ").bold = True
    p2.add_run(ex)
    p2.paragraph_format.space_after = Pt(6)
    p2.paragraph_format.left_indent = Inches(0.3)

doc.add_paragraph()

# ===================== SECTION 6: THUMB AND OPPOSITION =====================
add_heading(doc, "6. Role of the Thumb in Precision", level=1, color=(0x1F, 0x49, 0x7D))

doc.add_paragraph(
    "The thumb's unique capability for opposition is what makes precision handling possible. "
    "The carpometacarpal (CMC) joint is a saddle joint between the trapezium and base of the first metacarpal. "
    "It permits three degrees of freedom:"
)
thumb_movements = [
    "Abduction / Adduction (dorso-palmar axis)",
    "Flexion / Extension (transverse axis through trapezium)",
    "Opposition — a rotary movement about the longitudinal axis of the first metacarpal (3rd degree of freedom), "
    "enabled by the natural mismatch of the saddle joint surfaces. This is ESSENTIAL for precision grasping.",
]
for m in thumb_movements:
    add_bullet(doc, m)

doc.add_paragraph()

# ===================== SECTION 7: MUSCLES =====================
add_heading(doc, "7. Muscles Involved in Precision Handling", level=1, color=(0x1F, 0x49, 0x7D))

add_heading(doc, "7.1 Intrinsic Muscles (primary for fine precision)", level=2)

muscle_table = doc.add_table(rows=6, cols=3)
muscle_table.style = "Table Grid"

hdr2 = muscle_table.rows[0].cells
hdr2[0].text = "Muscle"
hdr2[1].text = "Role"
hdr2[2].text = "Nerve Supply"
for cell in hdr2:
    for para in cell.paragraphs:
        for run in para.runs:
            run.bold = True
    tc = cell._tc
    tcPr = tc.get_or_add_tcPr()
    shd = OxmlElement("w:shd")
    shd.set(qn("w:fill"), "2E75B6")
    shd.set(qn("w:val"), "clear")
    tcPr.append(shd)
    for para in cell.paragraphs:
        for run in para.runs:
            run.font.color.rgb = RGBColor(0xFF, 0xFF, 0xFF)

intrinsic_data = [
    ("Opponens pollicis", "Opposes thumb to fingers", "Median nerve"),
    ("Flexor pollicis brevis", "Flexes thumb MCP", "Median (sup. head), Ulnar (deep head)"),
    ("Abductor pollicis brevis", "Abducts + assists opposition", "Median nerve"),
    ("1st Dorsal Interosseus", "Abducts index finger", "Ulnar nerve"),
    ("Lumbricals 1 & 2", "Flex MCP, extend IP joints", "Median nerve"),
]
for i, (m, r, n) in enumerate(intrinsic_data):
    row = muscle_table.rows[i + 1].cells
    row[0].text = m
    row[1].text = r
    row[2].text = n
    for cell in row:
        tc = cell._tc
        tcPr = tc.get_or_add_tcPr()
        shd = OxmlElement("w:shd")
        fill = "DEEAF1" if i % 2 == 0 else "FFFFFF"
        shd.set(qn("w:fill"), fill)
        shd.set(qn("w:val"), "clear")
        tcPr.append(shd)

doc.add_paragraph()
add_heading(doc, "7.2 Extrinsic Muscles", level=2)

ext_table = doc.add_table(rows=5, cols=3)
ext_table.style = "Table Grid"

hdr3 = ext_table.rows[0].cells
hdr3[0].text = "Muscle"
hdr3[1].text = "Role"
hdr3[2].text = "Nerve Supply"
for cell in hdr3:
    for para in cell.paragraphs:
        for run in para.runs:
            run.bold = True
    tc = cell._tc
    tcPr = tc.get_or_add_tcPr()
    shd = OxmlElement("w:shd")
    shd.set(qn("w:fill"), "2E75B6")
    shd.set(qn("w:val"), "clear")
    tcPr.append(shd)
    for para in cell.paragraphs:
        for run in para.runs:
            run.font.color.rgb = RGBColor(0xFF, 0xFF, 0xFF)

extrinsic_data = [
    ("Flexor digitorum profundus (FDP)", "Flexes DIP joints; critical for tip pinch", "Median (lat.) + Ulnar (med.)"),
    ("Flexor digitorum superficialis (FDS)", "Flexes PIP joints", "Median nerve"),
    ("Flexor pollicis longus (FPL)", "Flexes thumb IP joint; essential for pinch", "Median nerve (AIN)"),
    ("Extensor digitorum", "Finger extension during opening phase", "Radial nerve (PIN)"),
]
for i, (m, r, n) in enumerate(extrinsic_data):
    row = ext_table.rows[i + 1].cells
    row[0].text = m
    row[1].text = r
    row[2].text = n
    for cell in row:
        tc = cell._tc
        tcPr = tc.get_or_add_tcPr()
        shd = OxmlElement("w:shd")
        fill = "DEEAF1" if i % 2 == 0 else "FFFFFF"
        shd.set(qn("w:fill"), fill)
        shd.set(qn("w:val"), "clear")
        tcPr.append(shd)

doc.add_paragraph()

# ===================== SECTION 8: NEURAL CONTROL =====================
add_heading(doc, "8. Neural Control of Precision Handling", level=1, color=(0x1F, 0x49, 0x7D))

doc.add_paragraph(
    "Precision grip is the type most often represented in the ventral premotor cortex (PMv / area F5). "
    "PMv neurons fire preferentially during precision grip rather than whole-hand prehension. These "
    "neurons encode the goal of the action (not individual muscles) — they fire whether the object is "
    "grasped by the right hand, left hand, or even the mouth."
)
doc.add_paragraph(
    "The primary motor cortex (M1) neurons active during precision pinch (low force, thumb-index) are "
    "largely silent during high-force power grip — highlighting that precision and power grip involve "
    "distinct cortical representations."
)

nerve_data = [
    ("Median nerve", "Thenar muscles (opponens, AbPB, FPB), lumbricals 1 & 2, FDS, FDP (radial half)",
     "Loss = inability to oppose thumb; loss of precision handling"),
    ("Ulnar nerve", "All interossei, hypothenar muscles, lumbricals 3 & 4, AdP, FPB (deep head)",
     "Loss = weak grip, Froment's sign, loss of fine control"),
    ("Radial nerve", "Wrist and finger extensors", "Loss = wrist drop; impairs opening phase of grip"),
]

nerve_table = doc.add_table(rows=4, cols=3)
nerve_table.style = "Table Grid"

hdr4 = nerve_table.rows[0].cells
hdr4[0].text = "Nerve"
hdr4[1].text = "Key Muscles"
hdr4[2].text = "Clinical Effect of Loss"
for cell in hdr4:
    for para in cell.paragraphs:
        for run in para.runs:
            run.bold = True
    tc = cell._tc
    tcPr = tc.get_or_add_tcPr()
    shd = OxmlElement("w:shd")
    shd.set(qn("w:fill"), "1F497D")
    shd.set(qn("w:val"), "clear")
    tcPr.append(shd)
    for para in cell.paragraphs:
        for run in para.runs:
            run.font.color.rgb = RGBColor(0xFF, 0xFF, 0xFF)

for i, (n, m, c) in enumerate(nerve_data):
    row = nerve_table.rows[i + 1].cells
    row[0].text = n
    row[1].text = m
    row[2].text = c
    for cell in row:
        tc = cell._tc
        tcPr = tc.get_or_add_tcPr()
        shd = OxmlElement("w:shd")
        fill = "DCE6F1" if i % 2 == 0 else "FFFFFF"
        shd.set(qn("w:fill"), fill)
        shd.set(qn("w:val"), "clear")
        tcPr.append(shd)

doc.add_paragraph()

# ===================== SECTION 9: CLINICAL SIGNIFICANCE =====================
add_heading(doc, "9. Clinical Significance", level=1, color=(0x1F, 0x49, 0x7D))

clinical_points = [
    ("Carpal Tunnel Syndrome",
     "Median nerve compression causes loss of thenar opposition and altered sensation over thumb/index finger, "
     "severely impairing precision handling."),
    ("Ulnar Nerve Palsy",
     "Froment's sign (compensatory IP flexion of the thumb using FPL) indicates failure of adductor pollicis "
     "(ulnar nerve), resulting in defective lateral/key pinch."),
    ("Thumb or Index Finger Loss",
     "Rated as more occupationally disabling than loss of other fingers because the precision pinch between "
     "thumb and index finger is lost."),
    ("Hand Osteoarthritis",
     "Workers performing precision grip tasks (burlers, spinners) develop more DIP joint OA than those using "
     "power grips — confirming the distinct mechanical loading between grip types."),
]
for name, desc in clinical_points:
    p = doc.add_paragraph()
    p.add_run(name + ": ").bold = True
    p.add_run(desc)
    p.paragraph_format.space_after = Pt(5)

doc.add_paragraph()

# ===================== SUMMARY TABLE =====================
add_heading(doc, "10. Summary Table: Prehension Activity Types", level=1, color=(0x1F, 0x49, 0x7D))

summary_data = [
    ("Pad-to-Pad (Pulp Pinch)", "Thumb pulp + finger pulp", "Picking up a coin", "Opponens pollicis, FPL, FDP"),
    ("Tip-to-Tip", "Thumb tip + finger tip", "Threading a needle", "FPL, FDP (distal)"),
    ("Pad-to-Side (Key Grip)", "Thumb pad + lateral index", "Turning a key", "Adductor pollicis, 1st DI"),
    ("Cylindrical Grip", "All fingers + palm", "Holding a glass", "FDS, FDP, intrinsics"),
    ("Spherical Grip", "All fingers spread", "Holding a ball", "Interossei, FDS, FDP"),
    ("Hook Grip", "Finger flexors only", "Carrying a briefcase", "FDP, FDS"),
    ("Lateral Prehension", "Adjacent finger sides", "Holding paper", "Interossei, extensors"),
]

sum_table = doc.add_table(rows=8, cols=4)
sum_table.style = "Table Grid"

hdr5 = sum_table.rows[0].cells
hdr5[0].text = "Type"
hdr5[1].text = "Contact Surface"
hdr5[2].text = "Example"
hdr5[3].text = "Key Muscles"
for cell in hdr5:
    for para in cell.paragraphs:
        for run in para.runs:
            run.bold = True
    tc = cell._tc
    tcPr = tc.get_or_add_tcPr()
    shd = OxmlElement("w:shd")
    shd.set(qn("w:fill"), "1F497D")
    shd.set(qn("w:val"), "clear")
    tcPr.append(shd)
    for para in cell.paragraphs:
        for run in para.runs:
            run.font.color.rgb = RGBColor(0xFF, 0xFF, 0xFF)

for i, row_data in enumerate(summary_data):
    row = sum_table.rows[i + 1].cells
    for j, val in enumerate(row_data):
        row[j].text = val
    for cell in row:
        tc = cell._tc
        tcPr = tc.get_or_add_tcPr()
        shd = OxmlElement("w:shd")
        fill = "DCE6F1" if i % 2 == 0 else "FFFFFF"
        shd.set(qn("w:fill"), fill)
        shd.set(qn("w:val"), "clear")
        tcPr.append(shd)

doc.add_paragraph()

# ===================== REFERENCES =====================
add_heading(doc, "References", level=1, color=(0x1F, 0x49, 0x7D))
refs = [
    "Schuenke M, Schulte E, Schumacher U. General Anatomy and Musculoskeletal System. THIEME Atlas of Anatomy. 2nd Ed. Thieme, 2014.",
    "Kandel ER, Koester JD, Mack SH, Siegelbaum SA. Principles of Neural Science, Sixth Edition. McGraw-Hill, 2021.",
    "Landsmeer JMF. Power grip and precision handling. Annals of Rheumatic Diseases. 1962;21:164-170.",
    "Kenhub. Anatomy of grip: How we hold different objects. kenhub.com/en/library/anatomy/anatomy-of-grip",
]
for ref in refs:
    p = doc.add_paragraph(style="List Number")
    p.add_run(ref)
    p.paragraph_format.space_after = Pt(3)

# Save
output_path = "/tmp/workspace/precision-hand/Precision_and_Prehension_Hand.docx"
doc.save(output_path)
print(f"Saved: {output_path}")