lab-hardware-cad

Lab Hardware CAD

Projete hardware de pesquisa físico como código fonte Python paramétrico, exporte STEP como o artefato autoritativo e verifique o resultado tanto numérica quanto visualmente antes que qualquer coisa seja fabricada.

A parte difícil do hardware de laboratório quase nunca é a geometria. É que a peça deve se acoplar a equipamentos cujas dimensões são fixadas por um padrão publicado ou um desenho de fornecedor. Um suporte que tem 0,5 mm de largura a mais não encaixa no leitor de placas; um canal com a proporção errada colapsa durante a ligação; um suporte cujo padrão de parafusos é 25,4 mm em vez de 25,0 mm não alcançará a mesa óptica. Esta habilidade existe para manter esses números corretos e verificados.

Quando usar

Use para qualquer solicitação para projetar, modelar ou fabricar uma peça física para um laboratório: chip, molde, suporte, adaptador, porta-objetos, rack, suporte, gabinete, dispositivo de fixação, acessório, arena ou labirinto. Use também para inspecionar ou modificar um arquivo STEP existente.

Não use para análise de elementos finitos, dinâmica de fluidos computacional, estrutura molecular ou plotagem científica. Essas são habilidades diferentes.

Configuração

uv venv --python 3.12 .venv-labcad
uv pip install --python .venv-labcad/bin/python "build123d==0.11.1" "matplotlib>=3.8"

build123d 0.11.1 requer Python >=3.10,<3.15 e puxa o kernel OpenCascade por meio de cadquery-ocp-novtk. O wheel é grande; instale uma vez por projeto e reutilize-o.

Todos os scripts incluídos aceitam --help. check.py standards é executado sem o build123d instalado.

Arquivos de modelo são executados, não analisados. gen.py, check.py e snapshot.py importam um *_model.py e chamam seu build(), que executa Python arbitrário no ambiente atual. Isso é inerente ao CAD paramétrico — o código fonte é o projeto. Execute apenas arquivos de modelo criados nesta sessão ou fornecidos pelo usuário de um local confiável. Se um modelo veio da internet, de um drive compartilhado ou de um colega não confiável, leia-o antes de executá-lo e diga que o fez.

Fluxo de trabalho obrigatório

Siga estas etapas em ordem. As etapas 5 e 6 não são opcionais, e a etapa 6 não é dispensada pela etapa 5 ser aprovada.

1. Roteie para uma família de dispositivos

Leia a solicitação, classifique-a e carregue exatamente uma referência de família. Não carregue todas as quatro — elas são longas, e misturar convenções entre famílias é uma fonte comum de erros.

Se a peça é	Carregue
Um chip, molde, rede de canais, célula de fluxo, vedação ou qualquer coisa com portas de fluido	references/microfluidics.md
Um suporte, poste, adaptador de breadboard, peça de sistema de gaiola, porta-filtro ou amostra em um caminho óptico	references/optomechanics.md
Um adaptador, inserto, rack ou suporte para placas, cubetas, tubos, lâminas ou placas de Petri	references/labware-adapters.md
Uma arena, labirinto, peça de fixação de cabeça, bocal, amarra ou gabinete montado em extrusão para trabalho com animais	references/behavior-rigs.md

Se a peça realmente abranger duas famílias — um chip microfluídico que é aparafusado a uma mesa óptica — carregue a família que possui a interface crítica, depois leia apenas a seção de interface da segunda. Indique em sua resposta para qual família você roteou.

2. Estabeleça as dimensões de interface antes de qualquer geometria

Cada peça tem pelo menos uma interface de encaixe. Antes de escrever código, anote para cada interface:

• a fonte da dimensão: um padrão publicado, um desenho de fornecedor ou uma medição do usuário;
• o valor nominal e tolerância;
• a folga ou interferência que você pretende, e por quê.

Consulte o número em assets/standards.json ou na referência da família. Nunca escreva uma dimensão de interface de memória. Se o número não estiver no arquivo de padrões ou na referência, peça ao usuário pelo desenho do fornecedor ou pela medição, em vez de adivinhar. Uma dimensão de interface adivinhada é o modo de falha mais caro nesta habilidade.

Um recurso que deve receber um componente padronizado é dimensionado em relação à condição de máximo material desse componente — nominal mais sua tolerância positiva — e só então recebe folga. Dimensionado a partir do nominal, ele se encaixa apenas na metade menor das peças conformes.

python scripts/check.py standards --list
python scripts/check.py standards --show slas-microplate-footprint

Os IDs de padrão incluídos (strings exatas; não adivinhe variantes): slas-microplate-footprint, slas-microplate-height, slas-microplate-flange, slas-well-positions-96, slas-well-positions-384, slas-well-positions-1536, cuvette-standard-10mm, optical-breadboard-metric, optical-breadboard-imperial, cage-system-30mm, sm1-lens-tube-thread.

Se a peça não se acoplar a nada nesta lista, isso é comum e aceitável: declare nenhuma interface, e nomeie cada dimensão de interface com sua fonte (especificação do usuário, desenho do fornecedor, medição) como não verificada no relatório. Nunca declare contra um padrão não relacionado para preencher a lacuna — uma declaração fabricada é pior do que um honesto "ninguém verificou isso".

3. Escolha o processo antes de escolher a geometria

Leia references/fabrication-limits.md. O processo determina a parede mínima, o recurso mínimo, a tolerância alcançável e se a peça sobrevive à autoclavação ou ao contato com seu solvente. FDM não pode manter ±0,05 mm; a resina SLA geralmente não é segura para contato com células sem pós-cura e teste. Registre o processo e o material no docstring do modelo.

4. Crie um modelo paramétrico

Escreva <part>_model.py. O código fonte é o artefato autoritativo — nunca edite manualmente um arquivo STEP exportado e nunca regenere a partir de uma malha.

Requisitos:

• Cada dimensão que um usuário possa alterar é uma constante nomeada no nível do módulo com unidades no nome: bore_d_mm, wall_t_mm, post_h_mm. Nenhum número isolado no corpo, exceto 0, 1 e 2.
• Exponha build() -> Part. gen.py a chama.
• Agrupe parâmetros em um bloco INTERFACE (dimensões fixadas por um padrão, anotadas com o ID do padrão) e um bloco DESIGN (dimensões que você é livre para escolher).
• Derive cada dimensão computada dentro de uma função, nunca no nível do módulo, para que as substituições --param realmente a alcancem.
• Declare uma função interfaces() retornando as dimensões que a peça deve encaixar, cada uma com seu ID de padrão e intenção. Isso é o que torna a interface verificável por máquina na etapa 5. intent é "envelope" quando o recurso deve aceitar qualquer peça conforme (um bolso, furo ou ranhura — verificado unilateralmente na condição de máximo material mais sua folga) e "match" quando esta peça deve, ela mesma, ser conforme (banda simétrica). clearance é a folga total pretendida em mm e deve ser não negativa. Declare apenas dimensões que restringem os recursos de encaixe desta peça — uma propriedade do equipamento de encaixe (a borda de uma mesa, a espessura típica de uma placa) não é uma interface sua. Se nenhum padrão incluído se aplicar, retorne [].
• Declare uma função checks() de calibradores passa/não-passa medidos a partir do sólido construído: uma região clear para tudo que deve passar ou encaixar (eixos de parafusos, corredores de feixe, a peça de encaixe na condição de máximo material caindo em seu bolso), uma região material para tudo que deve permanecer (uma crista, um ressalto, um assento de parafuso) e um limite bbox_* para cada limite de tamanho que o usuário declarou. Mapeie cada requisito geométrico na solicitação para uma entrada; estes capturam os erros que is_valid, a caixa delimitadora e os números declarados não podem ver. gen.py os executa em cada geração e falha na compilação quando um falha. Esquema e exemplos práticos: references/build123d-patterns.md.
• Coloque o processo, o material e cada fonte de interface no docstring do módulo.

"""Suporte para microplaca SLAS para um inserto de palco personalizado.

Processo: FDM, PETG, camada de 0,2 mm. Orçamento de tolerância +/-0,3 mm.
Interfaces:
  - Bolso da placa: ANSI/SLAS 1-2004 (R2012) pegada 127,76 x 85,48 mm, +/-0,25.
  - Parafusos do palco: medidos pelo usuário, centros de 40,0 mm (desenho em docs/stage.pdf).
"""
from build123d import *

# --- INTERFACE (fixada por padrão; não ajuste) ---
plate_l_mm = 127.76   # ANSI/SLAS 1-2004 nominal
plate_w_mm = 85.48    # ANSI/SLAS 1-2004 nominal
plate_tol_mm = 0.25   # ANSI/SLAS 1-2004; o bolso é dimensionado para nominal + isto
# --- DESIGN (livre) ---
pocket_clearance_mm = 0.40   # por lado; FDM, veja fabrication-limits.md
wall_t_mm = 3.0
floor_t_mm = 2.5
body_h_mm = 12.0


def pocket_mm() -> tuple[float, float]:
    """Bolso na condição de máximo material da placa mais folga por lado.

    Um bolso dimensionado a partir do nominal emperra em aproximadamente metade das placas conformes.
    """
    growth = plate_tol_mm + 2 * pocket_clearance_mm
    return plate_l_mm + growth, plate_w_mm + growth


def interfaces() -> list[dict]:
    """O que esta peça deve encaixar. `check.py interfaces` verifica cada entrada."""
    pocket_l, pocket_w = pocket_mm()
    return [
        {"feature": "comprimento do bolso da placa", "standard": "slas-microplate-footprint",
         "dimension": "footprint_length", "value": pocket_l,
         "intent": "envelope", "clearance": 2 * pocket_clearance_mm},
        {"feature": "largura do bolso da placa", "standard": "slas-microplate-footprint",
         "dimension": "footprint_width", "value": pocket_w,
         "intent": "envelope", "clearance": 2 * pocket_clearance_mm},
    ]


def checks() -> list[dict]:
    """Calibradores medidos a partir do sólido construído. Dimensionados a partir dos números do REQUISITO
    (MMC da placa, limite de altura do usuário), não dos parâmetros do bolso, para que um
    parâmetro errado não possa encolher o calibrador para corresponder à geometria errada."""
    depth = body_h_mm - floor_t_mm
    return [
        {"feature": "placa no MMC cai no bolso",
         "clear": {"box": (plate_l_mm + plate_tol_mm, plate_w_mm + plate_tol_mm, depth),
                   "at": [(0.0, 0.0, floor_t_mm + depth / 2)]}},
        {"feature": "abaixo de 15 mm para o palco", "bbox_z": {"max": 15.0}},
    ]


def build() -> Part:
    pocket_l, pocket_w = pocket_mm()
    with BuildPart() as carrier:
        Box(pocket_l + 2 * wall_t_mm, pocket_w + 2 * wall_t_mm, body_h_mm,
            align=(Align.CENTER, Align.CENTER, Align.MIN))
        with Locations((0, 0, floor_t_mm)):
            Box(pocket_l, pocket_w, body_h_mm, mode=Mode.SUBTRACT,
                align=(Align.CENTER, Align.CENTER, Align.MIN))
    return carrier.part

Veja references/build123d-patterns.md para a escolha entre builder e álgebra, o contrato interfaces(), esboço, seletores, filetes e furos para insertos rosqueados.

5. Gere e execute as verificações

python scripts/gen.py carrier_model.py --outdir out/
python scripts/check.py facts out/carrier.step
python scripts/check.py interfaces out/carrier.manifest.json
python scripts/check.py geometry out/carrier.step --model carrier_model.py

gen.py também avalia os calibradores checks() do modelo contra o sólido que acabou de construir, imprime cada PASS/FAIL, registra-os no manifesto e sai com código diferente de zero em caso de falha — então uma peça que viola sua própria geometria declarada nunca se torna silenciosamente um artefato. check.py geometry re-executa os mesmos calibradores contra o STEP exportado, que é o artefato autoritativo.

out/ é uma convenção temporária, não um requisito. Quando o usuário pediu entregáveis em um local específico, gere lá (--outdir .) ou copie o STEP, o manifesto e o DXF para lá antes de terminar — um entregável que existe apenas dentro de out/ não foi entregue.

gen.py escreve carrier.step (autoritativo), carrier.stl (visualização de malha e impressão) e carrier.manifest.json registrando o hash da fonte, os parâmetros resolvidos, as interfaces declaradas, as versões da biblioteca e a caixa delimitadora, volume e validade medidos. O manifesto é o registro de proveniência — mantenha-o com o artefato.

check.py facts relata is_valid, caixa delimitadora, volume, área de superfície, centro de massa e contagem de sólidos. Uma peça que relata is_valid: false tem geometria quebrada; corrija a fonte antes de continuar.

check.py interfaces avalia cada entrada que o modelo declarou contra o banco de dados de padrões e sai com código diferente de zero em caso de falha. Seja claro sobre o que ele verifica e o que não verifica: ele verifica os números declarados — capturando uma dimensão transcrita, o padrão errado e o dimensionamento nominal em vez de MMC — mas nunca mede a geometria construída, e um valor calculado a partir das mesmas constantes contra as quais é verificado passa com zero de margem por construção. Não o cite como evidência de que a geometria está correta; facts e a captura de tela são as verificações de geometria. Uma lista de declaração vazia passa: uma peça que não se acopla a nada no banco de dados incluído não tem nada a declarar, e suas dimensões de interface são, em vez disso, nomeadas como não verificadas no relatório.

Use interfaces em vez de check.py fit para qualquer coisa interna — um bolso, furo ou ranhura não aparece na caixa delimitadora externa da peça, que é o que fit mede. Recorra a fit apenas para verificar um número manualmente (--value footprint_length=128.81) ou quando o contorno da própria peça for a interface, como uma vedação cortada para a pegada de uma placa.

Para montagens, verifique se as peças não interferem:

python scripts/check.py clearance out/carrier.step out/lid.step --min 0.3

6. Capture a tela e realmente olhe para ela

python scripts/snapshot.py out/carrier.step --out out/carrier.png

Em seguida, leia o PNG. Esta etapa é obrigatória após cada geração e cada modificação. Verificações determinísticas sendo aprovadas não é motivo para pulá-la: is_valid e uma caixa delimitadora correta são ambos totalmente consistentes com um bolso cortado na face errada, um boss colocado fora do corpo ou um filete que comeu um recurso. Esses erros são óbvios em uma imagem e invisíveis nos números.

Conheça também os limites da renderização. Um recurso muito menor que o quadro — uma crista de molde de 0,3 mm em uma peça de 40 mm, um degrau de alargador em uma placa — pode não ser decidível a partir das vistas. Não relate ter visto algo que a imagem não pode resolver; isso é pior do que não olhar. Para tais recursos, a habilidade tem instrumentos: check.py bores imprime cada face cilíndrica (diâmetro, eixo, posição, vão, varredura) para que você possa reconciliar