matplotlib.github.com/_modules/matplotlib/collections.html at master · Carreau/matplotlib.github.com

History

2199 lines (1838 loc) · 276 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

639

640

641

642

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

675

676

677

678

679

680

681

682

683

684

685

686

687

688

689

690

691

692

693

694

695

696

697

698

699

700

701

702

703

704

705

706

707

708

709

710

711

712

713

714

715

716

717

718

719

720

721

722

723

724

725

726

727

728

729

730

731

732

733

734

735

736

737

738

739

740

741

742

743

744

745

746

747

748

749

750

751

752

753

754

755

756

757

758

759

760

761

762

763

764

765

766

767

768

769

770

771

772

773

774

775

776

777

778

779

780

781

782

783

784

785

786

787

788

789

790

791

792

793

794

795

796

797

798

799

800

801

802

803

804

805

806

807

808

809

810

811

812

813

814

815

816

817

818

819

820

821

822

823

824

825

826

827

828

829

830

831

832

833

834

835

836

837

838

839

840

841

842

843

844

845

846

847

848

849

850

851

852

853

854

855

856

857

858

859

860

861

862

863

864

865

866

867

868

869

870

871

872

873

874

875

876

877

878

879

880

881

882

883

884

885

886

887

888

889

890

891

892

893

894

895

896

897

898

899

900

901

902

903

904

905

906

907

908

909

910

911

912

913

914

915

916

917

918

919

920

921

922

923

924

925

926

927

928

929

930

931

932

933

934

935

936

937

938

939

940

941

942

943

944

945

946

947

948

949

950

951

952

953

954

955

956

957

958

959

960

961

962

963

964

965

966

967

968

969

970

971

972

973

974

975

976

977

978

979

980

981

982

983

984

985

986

987

988

989

990

991

992

993

994

995

996

997

998

999

1000

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>matplotlib.collections — Matplotlib 3.1.1 documentation</title>

type="text/css" />

type="text/css" />

title="Search within Matplotlib 3.1.1 documentation"

href="../../_static/opensearch.xml"/>

</head>

<body>

<div style="float: left; position: absolute; width: 496px; bottom: 0; padding-bottom: 24px">Version 3.1.1</div>

<div id="forkongithub"><a href="https://github.com/matplotlib/matplotlib">Fork me on GitHub</a></div>

</div>

<h3>Navigation</h3>

<ul>

<a href="../../genindex.html" title="General Index"

accesskey="I">index</a></li>

<a href="../../py-modindex.html" title="Python Module Index"

>modules</a> |</li>

<li><a href="../../gallery/index.html">examples</a>| </li>

<li><a href="../../tutorials/index.html">tutorials</a>| </li>

<li><a href="../../contents.html">contents</a> »</li>

<li><a href="../index.html" >Module code</a> »</li>

<li><a href="../matplotlib.html" accesskey="U">matplotlib</a> »</li>

</ul>

</div>

<h3>Quick search</h3>

</form>

</div>

<h3>Related Topics</h3>

<ul>

<li><a href="../../contents.html">Documentation overview</a><ul>

<li><a href="../index.html">Module code</a><ul>

<li><a href="../matplotlib.html">matplotlib</a><ul>

</ul></li>

</ul>

</div>

<h1>Source code for matplotlib.collections</h1><div class="highlight"><pre>

"""

Classes for the efficient drawing of large collections of objects that

share most properties, e.g., a large number of line segments or

polygons.

The classes are not meant to be as flexible as their single element

counterparts (e.g., you may not be able to select all line styles) but

they are meant to be fast for common use cases (e.g., a large set of solid

line segments).

"""

import math

from numbers import Number

import numpy as np

import matplotlib as mpl

from . import (_path, artist, cbook, cm, colors as mcolors, docstring,

lines as mlines, path as mpath, transforms)

import warnings

<div class="viewcode-block" id="Collection"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection">[docs]</a>@cbook._define_aliases({

"antialiased": ["antialiaseds", "aa"],

"edgecolor": ["edgecolors", "ec"],

"facecolor": ["facecolors", "fc"],

"linestyle": ["linestyles", "dashes", "ls"],

"linewidth": ["linewidths", "lw"],

})

class Collection(artist.Artist, cm.ScalarMappable):

"""

Base class for Collections. Must be subclassed to be usable.

All properties in a collection must be sequences or scalars;

if scalars, they will be converted to sequences. The

property of the ith element of the collection is::

prop[i % len(props)]

Exceptions are *capstyle* and *joinstyle* properties, these can

only be set globally for the whole collection.

Keyword arguments and default values:

* *edgecolors*: None

* *facecolors*: None

* *linewidths*: None

* *capstyle*: None

* *joinstyle*: None

* *antialiaseds*: None

* *offsets*: None

* *transOffset*: transforms.IdentityTransform()

* *offset_position*: 'screen' (default) or 'data'

* *norm*: None (optional for

:class:`matplotlib.cm.ScalarMappable`)

* *cmap*: None (optional for

:class:`matplotlib.cm.ScalarMappable`)

* *hatch*: None

* *zorder*: 1

*offsets* and *transOffset* are used to translate the patch after

rendering (default no offsets). If offset_position is 'screen'

(default) the offset is applied after the master transform has

been applied, that is, the offsets are in screen coordinates. If

offset_position is 'data', the offset is applied before the master

transform, i.e., the offsets are in data coordinates.

If any of *edgecolors*, *facecolors*, *linewidths*, *antialiaseds*

are None, they default to their :data:`matplotlib.rcParams` patch

setting, in sequence form.

The use of :class:`~matplotlib.cm.ScalarMappable` is optional. If

the :class:`~matplotlib.cm.ScalarMappable` matrix _A is not None

(i.e., a call to set_array has been made), at draw time a call to

scalar mappable will be made to set the face colors.

"""

_offsets = np.zeros((0, 2))

_transOffset = transforms.IdentityTransform()

#: Either a list of 3x3 arrays or an Nx3x3 array of transforms, suitable

#: for the `all_transforms` argument to

#: :meth:`~matplotlib.backend_bases.RendererBase.draw_path_collection`;

#: each 3x3 array is used to initialize an

#: :class:`~matplotlib.transforms.Affine2D` object.

#: Each kind of collection defines this based on its arguments.

_transforms = np.empty((0, 3, 3))

# Whether to draw an edge by default. Set on a

# subclass-by-subclass basis.

_edge_default = False

def __init__(self,

edgecolors=None,

facecolors=None,

linewidths=None,

linestyles='solid',

capstyle=None,

joinstyle=None,

antialiaseds=None,

offsets=None,

transOffset=None,

norm=None, # optional for ScalarMappable

cmap=None, # ditto

pickradius=5.0,

hatch=None,

urls=None,

offset_position='screen',

zorder=1,

**kwargs

):

"""

Create a Collection

%(Collection)s

"""

artist.Artist.__init__(self)

cm.ScalarMappable.__init__(self, norm, cmap)

# list of un-scaled dash patterns

# this is needed scaling the dash pattern by linewidth

self._us_linestyles = [(None, None)]

# list of dash patterns

self._linestyles = [(None, None)]

# list of unbroadcast/scaled linewidths

self._us_lw = [0]

self._linewidths = [0]

self._is_filled = True # May be modified by set_facecolor().

self._hatch_color = mcolors.to_rgba(mpl.rcParams['hatch.color'])

self.set_facecolor(facecolors)

self.set_edgecolor(edgecolors)

self.set_linewidth(linewidths)

self.set_linestyle(linestyles)

self.set_antialiased(antialiaseds)

self.set_pickradius(pickradius)

self.set_urls(urls)

self.set_hatch(hatch)

self.set_offset_position(offset_position)

self.set_zorder(zorder)

if capstyle:

self.set_capstyle(capstyle)

else:

self._capstyle = None

if joinstyle:

self.set_joinstyle(joinstyle)

else:

self._joinstyle = None

self._offsets = np.zeros((1, 2))

self._uniform_offsets = None

if offsets is not None:

offsets = np.asanyarray(offsets, float)

# Broadcast (2,) -> (1, 2) but nothing else.

if offsets.shape == (2,):

offsets = offsets[None, :]

if transOffset is not None:

self._offsets = offsets

self._transOffset = transOffset

else:

self._uniform_offsets = offsets

self._path_effects = None

self.update(kwargs)

self._paths = None

<div class="viewcode-block" id="Collection.get_paths"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_paths">[docs]</a> def get_paths(self):

return self._paths</div>

<div class="viewcode-block" id="Collection.set_paths"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_paths">[docs]</a> def set_paths(self):

raise NotImplementedError</div>

<div class="viewcode-block" id="Collection.get_transforms"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_transforms">[docs]</a> def get_transforms(self):

return self._transforms</div>

<div class="viewcode-block" id="Collection.get_offset_transform"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_offset_transform">[docs]</a> def get_offset_transform(self):

t = self._transOffset

if (not isinstance(t, transforms.Transform)

and hasattr(t, '_as_mpl_transform')):

t = t._as_mpl_transform(self.axes)

return t</div>

<div class="viewcode-block" id="Collection.get_datalim"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_datalim">[docs]</a> def get_datalim(self, transData):

transform = self.get_transform()

transOffset = self.get_offset_transform()

offsets = self._offsets

paths = self.get_paths()

if not transform.is_affine:

paths = [transform.transform_path_non_affine(p) for p in paths]

transform = transform.get_affine()

if not transOffset.is_affine:

offsets = transOffset.transform_non_affine(offsets)

transOffset = transOffset.get_affine()

if isinstance(offsets, np.ma.MaskedArray):

offsets = offsets.filled(np.nan)

# get_path_collection_extents handles nan but not masked arrays

if len(paths) and len(offsets):

result = mpath.get_path_collection_extents(

transform.frozen(), paths, self.get_transforms(),

offsets, transOffset.frozen())

result = result.inverse_transformed(transData)

else:

result = transforms.Bbox.null()

return result</div>

<div class="viewcode-block" id="Collection.get_window_extent"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_window_extent">[docs]</a> def get_window_extent(self, renderer):

# TODO: check to ensure that this does not fail for

# cases other than scatter plot legend

return self.get_datalim(transforms.IdentityTransform())</div>

def _prepare_points(self):

# Helper for drawing and hit testing.

transform = self.get_transform()

transOffset = self.get_offset_transform()

offsets = self._offsets

paths = self.get_paths()

if self.have_units():

paths = []

for path in self.get_paths():

vertices = path.vertices

xs, ys = vertices[:, 0], vertices[:, 1]

xs = self.convert_xunits(xs)

ys = self.convert_yunits(ys)

paths.append(mpath.Path(np.column_stack([xs, ys]), path.codes))

if offsets.size:

offsets = np.column_stack([xs, ys])

if not transform.is_affine:

for path in paths]

transform = transform.get_affine()

if not transOffset.is_affine:

# This might have changed an ndarray into a masked array.

transOffset = transOffset.get_affine()

# Changing from a masked array to nan-filled ndarray

# is probably most efficient at this point.

return transform, transOffset, offsets, paths

<div class="viewcode-block" id="Collection.draw"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.draw">[docs]</a> @artist.allow_rasterization

def draw(self, renderer):

if not self.get_visible():

return

renderer.open_group(self.__class__.__name__, self.get_gid())

self.update_scalarmappable()

transform, transOffset, offsets, paths = self._prepare_points()

gc = renderer.new_gc()

self._set_gc_clip(gc)

gc.set_snap(self.get_snap())

if self._hatch:

gc.set_hatch(self._hatch)

try:

gc.set_hatch_color(self._hatch_color)

except AttributeError:

# if we end up with a GC that does not have this method

cbook.warn_deprecated(

"3.1", message="Your backend does not support setting the "

"hatch color; such backends will become unsupported in "

"Matplotlib 3.3.")

if self.get_sketch_params() is not None:

gc.set_sketch_params(*self.get_sketch_params())

if self.get_path_effects():

from matplotlib.patheffects import PathEffectRenderer

renderer = PathEffectRenderer(self.get_path_effects(), renderer)

# If the collection is made up of a single shape/color/stroke,

# it can be rendered once and blitted multiple times, using

# `draw_markers` rather than `draw_path_collection`. This is

# *much* faster for Agg, and results in smaller file sizes in

# PDF/SVG/PS.

trans = self.get_transforms()

facecolors = self.get_facecolor()

edgecolors = self.get_edgecolor()

do_single_path_optimization = False

if (len(paths) == 1 and len(trans) <= 1 and

len(facecolors) == 1 and len(edgecolors) == 1 and

len(self._linewidths) == 1 and

self._linestyles == [(None, None)] and

len(self._antialiaseds) == 1 and len(self._urls) == 1 and

self.get_hatch() is None):

if len(trans):

combined_transform = (transforms.Affine2D(trans[0]) +

transform)

else:

combined_transform = transform

extents = paths[0].get_extents(combined_transform)

width, height = renderer.get_canvas_width_height()

if extents.width < width and extents.height < height:

do_single_path_optimization = True

if self._joinstyle:

gc.set_joinstyle(self._joinstyle)

if self._capstyle:

gc.set_capstyle(self._capstyle)

if do_single_path_optimization:

gc.set_foreground(tuple(edgecolors[0]))

gc.set_linewidth(self._linewidths[0])

gc.set_dashes(*self._linestyles[0])

gc.set_antialiased(self._antialiaseds[0])

gc.set_url(self._urls[0])

renderer.draw_markers(

gc, paths[0], combined_transform.frozen(),

mpath.Path(offsets), transOffset, tuple(facecolors[0]))

else:

renderer.draw_path_collection(

gc, transform.frozen(), paths,

self.get_transforms(), offsets, transOffset,

self.get_facecolor(), self.get_edgecolor(),

self._antialiaseds, self._urls,

self._offset_position)

gc.restore()

renderer.close_group(self.__class__.__name__)

self.stale = False</div>

<div class="viewcode-block" id="Collection.set_pickradius"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_pickradius">[docs]</a> def set_pickradius(self, pr):

"""

Set the pick radius used for containment tests.

Parameters

----------

d : float

Pick radius, in points.

"""

self._pickradius = pr</div>

<div class="viewcode-block" id="Collection.get_pickradius"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_pickradius">[docs]</a> def get_pickradius(self):

return self._pickradius</div>

<div class="viewcode-block" id="Collection.contains"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.contains">[docs]</a> def contains(self, mouseevent):

"""

Test whether the mouse event occurred in the collection.

Returns ``bool, dict(ind=itemlist)``, where every item in itemlist

contains the event.

"""

if self._contains is not None:

return self._contains(self, mouseevent)

if not self.get_visible():

return False, {}

pickradius = (

float(self._picker)

if isinstance(self._picker, Number) and

self._picker is not True # the bool, not just nonzero or 1

else self._pickradius)

ind = _path.point_in_path_collection(

mouseevent.x, mouseevent.y, pickradius,

offsets, transOffset, pickradius <= 0,

self.get_offset_position())

return len(ind) > 0, dict(ind=ind)</div>

<div class="viewcode-block" id="Collection.set_urls"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_urls">[docs]</a> def set_urls(self, urls):

"""

Parameters

----------

urls : List[str] or None

"""

self._urls = urls if urls is not None else [None]

self.stale = True</div>

<div class="viewcode-block" id="Collection.get_urls"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_urls">[docs]</a> def get_urls(self):

return self._urls</div>

<div class="viewcode-block" id="Collection.set_hatch"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_hatch">[docs]</a> def set_hatch(self, hatch):

r"""

Set the hatching pattern

*hatch* can be one of::

/ - diagonal hatching

\ - back diagonal

| - vertical

- - horizontal

+ - crossed

x - crossed diagonal

o - small circle

O - large circle

. - dots

* - stars

Letters can be combined, in which case all the specified

hatchings are done. If same letter repeats, it increases the

density of hatching of that pattern.

Hatching is supported in the PostScript, PDF, SVG and Agg

backends only.

Unlike other properties such as linewidth and colors, hatching

can only be specified for the collection as a whole, not separately

for each member.

Parameters

----------

hatch : {'/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}

"""

self._hatch = hatch

self.stale = True</div>

<div class="viewcode-block" id="Collection.get_hatch"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_hatch">[docs]</a> def get_hatch(self):

"""Return the current hatching pattern."""

return self._hatch</div>

<div class="viewcode-block" id="Collection.set_offsets"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_offsets">[docs]</a> def set_offsets(self, offsets):

"""

Set the offsets for the collection.

Parameters

----------

offsets : float or sequence of floats

"""

offsets = offsets[None, :]

# This decision is based on how they are initialized above in __init__.

if self._uniform_offsets is None:

self._offsets = offsets

else:

self._uniform_offsets = offsets

self.stale = True</div>

<div class="viewcode-block" id="Collection.get_offsets"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_offsets">[docs]</a> def get_offsets(self):

"""Return the offsets for the collection."""

# This decision is based on how they are initialized above in __init__.

if self._uniform_offsets is None:

return self._offsets

else:

return self._uniform_offsets</div>

<div class="viewcode-block" id="Collection.set_offset_position"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_offset_position">[docs]</a> def set_offset_position(self, offset_position):

"""

Set how offsets are applied. If *offset_position* is 'screen'

(default) the offset is applied after the master transform has

been applied, that is, the offsets are in screen coordinates.

If offset_position is 'data', the offset is applied before the

master transform, i.e., the offsets are in data coordinates.

Parameters

----------

offset_position : {'screen', 'data'}

"""

cbook._check_in_list(['screen', 'data'],

offset_position=offset_position)

self._offset_position = offset_position

self.stale = True</div>

<div class="viewcode-block" id="Collection.get_offset_position"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_offset_position">[docs]</a> def get_offset_position(self):

"""

Returns how offsets are applied for the collection. If

*offset_position* is 'screen', the offset is applied after the

master transform has been applied, that is, the offsets are in

screen coordinates. If offset_position is 'data', the offset

is applied before the master transform, i.e., the offsets are

in data coordinates.

"""

return self._offset_position</div>

<div class="viewcode-block" id="Collection.set_linewidth"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_linewidth">[docs]</a> def set_linewidth(self, lw):

"""

Set the linewidth(s) for the collection. *lw* can be a scalar

or a sequence; if it is a sequence the patches will cycle

through the sequence

Parameters

----------

lw : float or sequence of floats

"""

if lw is None:

lw = mpl.rcParams['patch.linewidth']

if lw is None:

# get the un-scaled/broadcast lw

self._us_lw = np.atleast_1d(np.asarray(lw))

# scale all of the dash patterns.

self._linewidths, self._linestyles = self._bcast_lwls(

self._us_lw, self._us_linestyles)

self.stale = True</div>

<div class="viewcode-block" id="Collection.set_linestyle"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_linestyle">[docs]</a> def set_linestyle(self, ls):

"""

Set the linestyle(s) for the collection.

=========================== =================

linestyle description

=========================== =================

``'-'`` or ``'solid'`` solid line

``'--'`` or ``'dashed'`` dashed line

``'-.'`` or ``'dashdot'`` dash-dotted line

``':'`` or ``'dotted'`` dotted line

=========================== =================

Alternatively a dash tuple of the following form can be provided::

(offset, onoffseq),

where ``onoffseq`` is an even length tuple of on and off ink in points.

Parameters

----------

ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}

The line style.

"""

try:

if isinstance(ls, str):

ls = cbook.ls_mapper.get(ls, ls)

else:

try:

except ValueError:

dashes = [mlines._get_dash_pattern(x) for x in ls]

except ValueError:

raise ValueError(

'Do not know how to convert {!r} to dashes'.format(ls))

# get the list of raw 'unscaled' dash patterns

self._us_linestyles = dashes

# broadcast and scale the lw and dash patterns

<div class="viewcode-block" id="Collection.set_capstyle"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_capstyle">[docs]</a> def set_capstyle(self, cs):

"""

Set the capstyle for the collection (for all its elements).

Parameters

----------

cs : {'butt', 'round', 'projecting'}

The capstyle

"""

if cs in ('butt', 'round', 'projecting'):

self._capstyle = cs

else:

raise ValueError('Unrecognized cap style. Found %s' % cs)</div>

<div class="viewcode-block" id="Collection.get_capstyle"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_capstyle">[docs]</a> def get_capstyle(self):

return self._capstyle</div>

<div class="viewcode-block" id="Collection.set_joinstyle"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_joinstyle">[docs]</a> def set_joinstyle(self, js):

"""

Set the joinstyle for the collection (for all its elements).

Parameters

----------

js : {'miter', 'round', 'bevel'}

The joinstyle

"""

if js in ('miter', 'round', 'bevel'):

self._joinstyle = js

else:

raise ValueError('Unrecognized join style. Found %s' % js)</div>

<div class="viewcode-block" id="Collection.get_joinstyle"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_joinstyle">[docs]</a> def get_joinstyle(self):

return self._joinstyle</div>

@staticmethod

def _bcast_lwls(linewidths, dashes):

"""

Internal helper function to broadcast + scale ls/lw

In the collection drawing code, the linewidth and linestyle are cycled

through as circular buffers (via ``v[i % len(v)]``). Thus, if we are

going to scale the dash pattern at set time (not draw time) we need to

do the broadcasting now and expand both lists to be the same length.

Parameters

----------

linewidths : list

line widths of collection

dashes : list

dash specification (offset, (dash pattern tuple))

Returns

-------

linewidths, dashes : list

Will be the same length, dashes are scaled by paired linewidth

"""

if mpl.rcParams['_internal.classic_mode']:

return linewidths, dashes

# make sure they are the same length so we can zip them

if len(dashes) != len(linewidths):

l_dashes = len(dashes)

l_lw = len(linewidths)

gcd = math.gcd(l_dashes, l_lw)

dashes = list(dashes) * (l_lw // gcd)

linewidths = list(linewidths) * (l_dashes // gcd)

# scale the dash patters

dashes = [mlines._scale_dashes(o, d, lw)

for (o, d), lw in zip(dashes, linewidths)]

return linewidths, dashes

<div class="viewcode-block" id="Collection.set_antialiased"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_antialiased">[docs]</a> def set_antialiased(self, aa):

"""

Set the antialiasing state for rendering.

Parameters

----------

aa : bool or sequence of bools

"""

if aa is None:

aa = mpl.rcParams['patch.antialiased']

self._antialiaseds = np.atleast_1d(np.asarray(aa, bool))

self.stale = True</div>

<div class="viewcode-block" id="Collection.set_color"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_color">[docs]</a> def set_color(self, c):

"""

Set both the edgecolor and the facecolor.

Parameters

----------

c : color or sequence of rgba tuples

See Also

--------

Collection.set_facecolor, Collection.set_edgecolor

For setting the edge or face color individually.

"""

self.set_facecolor(c)

self.set_edgecolor(c)</div>

def _set_facecolor(self, c):

if c is None:

c = mpl.rcParams['patch.facecolor']

self._is_filled = True

try:

if c.lower() == 'none':

self._is_filled = False

except AttributeError:

pass

self._facecolors = mcolors.to_rgba_array(c, self._alpha)

self.stale = True

<div class="viewcode-block" id="Collection.set_facecolor"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_facecolor">[docs]</a> def set_facecolor(self, c):

"""

Set the facecolor(s) of the collection. *c* can be a

matplotlib color spec (all patches have same color), or a

sequence of specs; if it is a sequence the patches will

cycle through the sequence.

If *c* is 'none', the patch will not be filled.

Parameters

----------

c : color or sequence of colors

"""

self._original_facecolor = c

self._set_facecolor(c)</div>

<div class="viewcode-block" id="Collection.get_facecolor"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_facecolor">[docs]</a> def get_facecolor(self):

return self._facecolors</div>

<div class="viewcode-block" id="Collection.get_edgecolor"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_edgecolor">[docs]</a> def get_edgecolor(self):

if cbook._str_equal(self._edgecolors, 'face'):

return self.get_facecolor()

else:

return self._edgecolors</div>

def _set_edgecolor(self, c):

set_hatch_color = True

if c is None:

if (mpl.rcParams['patch.force_edgecolor'] or

not self._is_filled or self._edge_default):

else:

c = 'none'

set_hatch_color = False

self._is_stroked = True

try:

self._is_stroked = False

except AttributeError:

pass

try:

self._edgecolors = 'face'

return

except AttributeError:

pass

self._edgecolors = mcolors.to_rgba_array(c, self._alpha)

if set_hatch_color and len(self._edgecolors):

self._hatch_color = tuple(self._edgecolors[0])

self.stale = True

<div class="viewcode-block" id="Collection.set_edgecolor"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_edgecolor">[docs]</a> def set_edgecolor(self, c):

"""

Set the edgecolor(s) of the collection.

Parameters

----------

c : color or sequence of colors or 'face'

The collection edgecolor(s). If a sequence, the patches cycle

through it. If 'face', match the facecolor.

"""

self._original_edgecolor = c

self._set_edgecolor(c)</div>

<div class="viewcode-block" id="Collection.set_alpha"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.set_alpha">[docs]</a> def set_alpha(self, alpha):

"""

Set the alpha transparencies of the collection.

Parameters

----------

alpha : float or None

"""

if alpha is not None:

try:

float(alpha)

except TypeError:

raise TypeError('alpha must be a float or None')

self.update_dict['array'] = True

artist.Artist.set_alpha(self, alpha)

self._set_facecolor(self._original_facecolor)

self._set_edgecolor(self._original_edgecolor)</div>

<div class="viewcode-block" id="Collection.get_linewidth"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_linewidth">[docs]</a> def get_linewidth(self):

return self._linewidths</div>

<div class="viewcode-block" id="Collection.get_linestyle"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_linestyle">[docs]</a> def get_linestyle(self):

return self._linestyles</div>

<div class="viewcode-block" id="Collection.update_scalarmappable"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.update_scalarmappable">[docs]</a> def update_scalarmappable(self):

"""Update colors from the scalar mappable array, if it is not None."""

if self._A is None:

return

if self._A.ndim > 1:

raise ValueError('Collections can only map rank 1 arrays')

if not self.check_update("array"):

return

if self._is_filled:

self._facecolors = self.to_rgba(self._A, self._alpha)

elif self._is_stroked:

self._edgecolors = self.to_rgba(self._A, self._alpha)

self.stale = True</div>

<div class="viewcode-block" id="Collection.get_fill"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.get_fill">[docs]</a> def get_fill(self):

'return whether fill is set'

return self._is_filled</div>

<div class="viewcode-block" id="Collection.update_from"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.Collection.update_from">[docs]</a> def update_from(self, other):

'copy properties from other to self'

artist.Artist.update_from(self, other)

self._antialiaseds = other._antialiaseds

self._original_edgecolor = other._original_edgecolor

self._edgecolors = other._edgecolors

self._original_facecolor = other._original_facecolor

self._facecolors = other._facecolors

self._linewidths = other._linewidths

self._linestyles = other._linestyles

self._us_linestyles = other._us_linestyles

self._pickradius = other._pickradius

self._hatch = other._hatch

# update_from for scalarmappable

self._A = other._A

self.norm = other.norm

self.cmap = other.cmap

# self.update_dict = other.update_dict # do we need to copy this? -JJL

self.stale = True</div></div>

# these are not available for the object inspector until after the

# class is built so we define an initial set here for the init

# function and they will be overridden after object defn

docstring.interpd.update(Collection="""\

Valid Collection keyword arguments:

* *edgecolors*: None

* *facecolors*: None

* *linewidths*: None

* *antialiaseds*: None

* *offsets*: None

* *transOffset*: transforms.IdentityTransform()

* *norm*: None (optional for

:class:`matplotlib.cm.ScalarMappable`)

* *cmap*: None (optional for

:class:`matplotlib.cm.ScalarMappable`)

*offsets* and *transOffset* are used to translate the patch after

rendering (default no offsets)

If any of *edgecolors*, *facecolors*, *linewidths*, *antialiaseds*

are None, they default to their :data:`matplotlib.rcParams` patch

setting, in sequence form.

""")

class _CollectionWithSizes(Collection):

"""

Base class for collections that have an array of sizes.

"""

_factor = 1.0

def get_sizes(self):

"""

Returns the sizes of the elements in the collection. The

value represents the 'area' of the element.

Returns

-------

sizes : array

The 'area' of each element.

"""

return self._sizes

def set_sizes(self, sizes, dpi=72.0):

"""

Set the sizes of each member of the collection.

Parameters

----------

sizes : ndarray or None

The size to set for each element of the collection. The

value is the 'area' of the element.

dpi : float

The dpi of the canvas. Defaults to 72.0.

"""

if sizes is None:

self._sizes = np.array([])

self._transforms = np.empty((0, 3, 3))

else:

self._transforms = np.zeros((len(self._sizes), 3, 3))

scale = np.sqrt(self._sizes) * dpi / 72.0 * self._factor

self._transforms[:, 0, 0] = scale

self._transforms[:, 1, 1] = scale

self._transforms[:, 2, 2] = 1.0

self.stale = True

@artist.allow_rasterization

def draw(self, renderer):

self.set_sizes(self._sizes, self.figure.dpi)

Collection.draw(self, renderer)

<div class="viewcode-block" id="PathCollection"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.PathCollection">[docs]</a>class PathCollection(_CollectionWithSizes):

"""

This is the most basic :class:`Collection` subclass.

A :class:`PathCollection` is e.g. created by a :meth:`~.Axes.scatter` plot.

"""

@docstring.dedent_interpd

def __init__(self, paths, sizes=None, **kwargs):

"""

*paths* is a sequence of :class:`matplotlib.path.Path`

instances.

%(Collection)s

"""

Collection.__init__(self, **kwargs)

self.set_paths(paths)

self.set_sizes(sizes)

self.stale = True

<div class="viewcode-block" id="PathCollection.set_paths"><a class="viewcode-back" href="../../api/collections_api.html#matplotlib.collections.PathCollection.set_paths">[docs]</a> def set_paths(self, paths):

View remainder of file in raw view

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

collections.html

Latest commit

History

collections.html

File metadata and controls